{
  "openapi": "3.1.1",
  "info": {
    "title": "Buzzberg MCP HTTP transport and discovery",
    "version": "1.0.0",
    "description": "Buzzberg research is exposed through Model Context Protocol, not a parallel REST data API. This document describes the existing Streamable HTTP transport and public discovery. Discover individual typed research tools in the linked catalog or authenticated MCP tools/list; call them through MCP tools/call. Public schemas do not authorize execution. OAuth browser sign-in and consent is the primary connection path. Existing personal keys remain supported, but new personal keys are not issued.",
    "contact": {"name": "Buzzberg support", "url": "https://buzzberg.ai/about#contact", "email": "support@buzzberg.ai"}
  },
  "servers": [{"url": "https://mcp.buzzberg.ai"}],
  "externalDocs": {"description": "MCP setup, examples and account access", "url": "https://buzzberg.ai/mcp"},
  "paths": {
    "/mcp": {
      "post": {
        "operationId": "sendMcpMessage",
        "summary": "Send a Model Context Protocol JSON-RPC message",
        "description": "Use an MCP client for initialization, tools/list, tools/call and notifications. Send Accept: application/json, text/event-stream. Subsequent requests include the negotiated MCP-Protocol-Version. Tool names and parameter schemas are published at https://buzzberg.ai/mcp/tools.json. This endpoint is stateless in the current deployment; do not invent an MCP session ID. Tool execution requires an authorized account and applicable tool permissions. On 429, honor Retry-After and avoid parallel retry batches.",
        "security": [{"OAuth": ["mcp"]}, {"LegacyBearer": []}],
        "parameters": [
          {"name": "MCP-Protocol-Version", "in": "header", "required": false, "description": "Negotiated MCP version on requests after initialization.", "schema": {"type": "string"}},
          {"name": "Accept", "in": "header", "required": true, "description": "An MCP HTTP client must accept both JSON and server-sent events.", "schema": {"type": "string"}, "example": "application/json, text/event-stream"}
        ],
        "requestBody": {
          "required": true,
          "content": {"application/json": {
            "schema": {"$ref": "#/components/schemas/McpMessage"},
            "examples": {
              "listTools": {"summary": "Discover tools after MCP initialization", "value": {"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}},
              "initialize": {"summary": "Initialize using a supported MCP protocol version", "value": {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "example-client", "version": "1.0"}}}}
            }
          }}
        },
        "responses": {
          "200": {"description": "MCP JSON-RPC result/error or a server-sent event stream, as negotiated by the transport.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/McpResponse"}}, "text/event-stream": {"schema": {"type": "string"}}}},
          "202": {"description": "Accepted MCP notification; no response body."},
          "400": {"description": "Invalid transport or protocol request.", "content": {"application/json": {"schema": {"type": "object"}}, "text/plain": {"schema": {"type": "string"}}}},
          "401": {"description": "Missing or invalid authority. Follow WWW-Authenticate to OAuth resource discovery.", "headers": {"WWW-Authenticate": {"description": "Bearer challenge including scope and resource_metadata.", "schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AccessError"}}}},
          "403": {"description": "Insufficient scope, revoked legacy key or refused account access.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AccessError"}}}},
          "406": {"description": "The client did not accept the required response media types."},
          "413": {"description": "Request exceeds the transport size limit.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AccessError"}}}},
          "429": {"description": "Per-account, per-caller or global budget exhausted; retry after the advertised delay.", "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer", "minimum": 0}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AccessError"}}}},
          "503": {"description": "Authorization or security state temporarily unavailable; no permission was granted.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AccessError"}}}}
        }
      }
    },
    "/.well-known/oauth-protected-resource/mcp": {
      "get": {
        "operationId": "getMcpProtectedResourceMetadata",
        "summary": "Discover the MCP protected resource and required scope",
        "description": "RFC 9728 metadata. The resource identifier includes /mcp and matches the client connection URL.",
        "security": [],
        "responses": {"200": {"description": "Published resource metadata.", "content": {"application/json": {"schema": {"type": "object", "required": ["resource", "authorization_servers", "scopes_supported"], "properties": {"resource": {"type": "string", "format": "uri"}, "authorization_servers": {"type": "array", "items": {"type": "string", "format": "uri"}}, "scopes_supported": {"type": "array", "items": {"type": "string"}}, "bearer_methods_supported": {"type": "array", "items": {"type": "string"}}}}}}}}
      }
    },
    "/.well-known/oauth-authorization-server": {
      "get": {
        "operationId": "getMcpAuthorizationServerMetadata",
        "summary": "Discover OAuth authorization and token endpoints",
        "description": "RFC 8414 metadata from the deployed authorization server. Read this document for current registration, revocation and PKCE capabilities.",
        "security": [],
        "responses": {"200": {"description": "Authorization server metadata.", "content": {"application/json": {"schema": {"type": "object", "required": ["issuer", "authorization_endpoint", "token_endpoint"], "properties": {"issuer": {"type": "string", "format": "uri"}, "authorization_endpoint": {"type": "string", "format": "uri"}, "token_endpoint": {"type": "string", "format": "uri"}, "scopes_supported": {"type": "array", "items": {"type": "string"}}}}}}}}
      }
    },
    "/mcp/tools.json": {
      "servers": [{"url": "https://buzzberg.ai"}],
      "get": {
        "operationId": "getPublicMcpToolCatalog",
        "summary": "Read public tool documentation without executing tools",
        "description": "Release-generated documentation in the MCP tools/list result shape. The authenticated runtime remains the authority for available tools. Input/output schemas are JSON Schema objects from the actual registered tools.",
        "security": [],
        "responses": {"200": {"description": "Tool names, descriptions and schemas.", "content": {"application/json": {"schema": {"type": "object", "required": ["tools"], "properties": {"tools": {"type": "array", "items": {"type": "object", "required": ["name", "inputSchema"], "properties": {"name": {"type": "string"}, "description": {"type": "string"}, "inputSchema": {"type": "object"}, "outputSchema": {"type": "object"}}}}}}}}}}
      }
    }
  },
  "components": {
    "securitySchemes": {
      "OAuth": {"type": "oauth2", "description": "Primary connection: authorization code with PKCE S256 and RFC 8707 resource=https://mcp.buzzberg.ai/mcp. Browser sign-in and consent are required. The current permission scope is mcp; separate read/write scopes are not advertised.", "flows": {"authorizationCode": {"authorizationUrl": "https://mcp.buzzberg.ai/authorize", "tokenUrl": "https://mcp.buzzberg.ai/token", "scopes": {"mcp": "Access Buzzberg MCP using the consenting account, subject to tool permissions and shared limits."}}}},
      "LegacyBearer": {"type": "http", "scheme": "bearer", "description": "Existing personal keys only. New personal key issuance is retired; use OAuth for new connections."}
    },
    "schemas": {
      "McpMessage": {"type": "object", "required": ["jsonrpc", "method"], "properties": {"jsonrpc": {"const": "2.0"}, "id": {"type": ["string", "integer"], "description": "Present on a request; omitted on a notification."}, "method": {"type": "string", "description": "An MCP JSON-RPC method such as initialize, tools/list or tools/call."}, "params": {"type": "object", "description": "Parameters defined by the MCP method. For tools/call, use the named tool's inputSchema from the public catalog."}}},
      "McpResponse": {"type": "object", "required": ["jsonrpc", "id"], "properties": {"jsonrpc": {"const": "2.0"}, "id": {"type": ["string", "integer", "null"]}, "result": {"type": "object"}, "error": {"type": "object", "required": ["code", "message"], "properties": {"code": {"type": "integer"}, "message": {"type": "string"}, "data": {}}}}, "oneOf": [{"required": ["result"], "not": {"required": ["error"]}}, {"required": ["error"], "not": {"required": ["result"]}}]},
      "AccessError": {"type": "object", "required": ["error"], "properties": {"error": {"type": "string"}, "code": {"type": "string"}, "detail": {"type": "string"}, "resolution": {"type": "string"}, "retry_after_seconds": {"type": "integer", "minimum": 0}}}
    }
  }
}