{
  "openapi": "3.1.1",
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "info": {
    "title": "Brief AI MCP API",
    "version": "1.0.0",
    "description": "The authenticated BriefHQ Model Context Protocol (MCP) gateway. Connect an MCP client to the Streamable HTTP endpoint to give an agent access to product context, decisions, documents, personas, features, and strategy. MCP clients should discover individual tool names and their input schemas with the protocol's `tools/list` method after OAuth authentication.",
    "termsOfService": "https://briefhq.ai/terms-of-service/",
    "contact": {
      "name": "BriefHQ developer support",
      "url": "https://briefhq.ai/support/",
      "email": "hello@briefhq.ai"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://briefhq.ai/terms-of-service/"
    }
  },
  "externalDocs": {
    "description": "BriefHQ developer resources and MCP setup",
    "url": "https://briefhq.ai/developers/"
  },
  "servers": [
    {
      "url": "https://app.briefhq.ai",
      "description": "Brief AI production application and MCP server"
    }
  ],
  "tags": [
    {
      "name": "MCP",
      "description": "Model Context Protocol Streamable HTTP transport"
    },
    {
      "name": "OAuth discovery",
      "description": "RFC 9728 protected-resource and RFC 8414 authorization-server metadata"
    }
  ],
  "paths": {
    "/mcp": {
      "get": {
        "operationId": "openMcpEventStream",
        "summary": "Open the MCP server event stream",
        "description": "Opens the server-to-client side of Brief's Streamable HTTP transport. Authenticated MCP clients send `Accept: text/event-stream` and may include `Mcp-Session-Id` after initialization.",
        "tags": ["MCP"],
        "parameters": [
          { "$ref": "#/components/parameters/McpProtocolVersion" },
          { "$ref": "#/components/parameters/McpSessionId" },
          { "$ref": "#/components/parameters/LastEventId" }
        ],
        "security": [{ "oauth2": ["mcp:read"] }],
        "responses": {
          "200": {
            "description": "An MCP Server-Sent Events stream.",
            "content": {
              "text/event-stream": {
                "schema": { "type": "string" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "406": { "$ref": "#/components/responses/NotAcceptable" },
          "default": { "$ref": "#/components/responses/ApiError" }
        }
      },
      "post": {
        "operationId": "sendMcpMessage",
        "summary": "Send a JSON-RPC message to Brief MCP",
        "description": "Sends one JSON-RPC 2.0 request or notification to the Brief MCP server. Clients must send `Accept: application/json, text/event-stream` and support either response type. MCP does not support JSON-RPC batches. For the deployed session-based compatibility profile, start with `initialize`, send `notifications/initialized`, then call `tools/list` to retrieve the authoritative function names and JSON Schemas before using `tools/call`.",
        "tags": ["MCP"],
        "parameters": [
          { "$ref": "#/components/parameters/McpProtocolVersion" },
          { "$ref": "#/components/parameters/McpSessionId" }
        ],
        "security": [{ "oauth2": ["mcp:read", "mcp:write"] }],
        "requestBody": {
          "required": true,
          "description": "One UTF-8 JSON-RPC 2.0 MCP request or notification.",
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  { "$ref": "#/components/schemas/JsonRpcRequest" },
                  { "$ref": "#/components/schemas/JsonRpcNotification" }
                ]
              },
              "examples": {
                "initialize": {
                  "summary": "Initialize an MCP session",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": "initialize-1",
                    "method": "initialize",
                    "params": {
                      "protocolVersion": "2025-11-25",
                      "capabilities": {},
                      "clientInfo": { "name": "example-agent", "version": "1.0.0" }
                    }
                  }
                },
                "listTools": {
                  "summary": "Discover function-calling-compatible tools",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": "tools-1",
                    "method": "tools/list",
                    "params": {}
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A JSON-RPC response, or an event stream containing one or more JSON-RPC responses.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/JsonRpcSuccess" },
                    { "$ref": "#/components/schemas/JsonRpcError" }
                  ]
                }
              },
              "text/event-stream": {
                "schema": { "type": "string" }
              }
            }
          },
          "202": {
            "description": "The JSON-RPC notification was accepted; no response body is returned."
          },
          "400": { "$ref": "#/components/responses/InvalidJsonRpc" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "406": { "$ref": "#/components/responses/NotAcceptable" },
          "default": { "$ref": "#/components/responses/ApiError" }
        }
      },
      "delete": {
        "operationId": "closeMcpSession",
        "summary": "Close an MCP session",
        "description": "Explicitly terminates the MCP session identified by the `Mcp-Session-Id` request header.",
        "tags": ["MCP"],
        "parameters": [
          { "$ref": "#/components/parameters/McpProtocolVersion" },
          { "$ref": "#/components/parameters/RequiredMcpSessionId" }
        ],
        "security": [{ "oauth2": ["mcp:write"] }],
        "responses": {
          "204": { "description": "The session was terminated." },
          "400": { "$ref": "#/components/responses/ApiError" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/ApiError" },
          "default": { "$ref": "#/components/responses/ApiError" }
        }
      }
    },
    "/.well-known/oauth-protected-resource/mcp": {
      "get": {
        "operationId": "getMcpProtectedResourceMetadata",
        "summary": "Get Brief MCP protected-resource metadata",
        "description": "Returns RFC 9728 metadata that tells an MCP client which authorization server protects the Brief MCP endpoint.",
        "tags": ["OAuth discovery"],
        "security": [],
        "responses": {
          "200": {
            "description": "Protected-resource metadata.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ProtectedResourceMetadata" } }
            }
          },
          "4XX": { "$ref": "#/components/responses/ApiError" },
          "default": { "$ref": "#/components/responses/ApiError" }
        }
      }
    },
    "/.well-known/oauth-authorization-server": {
      "get": {
        "operationId": "getOAuthAuthorizationServerMetadata",
        "summary": "Get Brief OAuth authorization-server metadata",
        "description": "Returns RFC 8414 metadata for OAuth client registration, authorization, token exchange, refresh, device authorization, and revocation.",
        "tags": ["OAuth discovery"],
        "security": [],
        "responses": {
          "200": {
            "description": "Authorization-server metadata.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationServerMetadata" } }
            }
          },
          "4XX": { "$ref": "#/components/responses/ApiError" },
          "default": { "$ref": "#/components/responses/ApiError" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.1 authorization-code flow with PKCE. MCP clients can use dynamic client registration and discover all URLs from the authorization-server metadata endpoint.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://app.briefhq.ai/api/oauth/authorize",
            "tokenUrl": "https://app.briefhq.ai/api/oauth/token",
            "refreshUrl": "https://app.briefhq.ai/api/oauth/token",
            "scopes": {
              "mcp:read": "Read product context through MCP",
              "mcp:write": "Create or update authorized Brief content through MCP"
            }
          }
        }
      }
    },
    "parameters": {
      "McpProtocolVersion": {
        "name": "MCP-Protocol-Version",
        "in": "header",
        "required": false,
        "description": "The MCP protocol version negotiated during initialization.",
        "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2025-11-25" }
      },
      "McpSessionId": {
        "name": "Mcp-Session-Id",
        "in": "header",
        "required": false,
        "description": "The opaque session identifier returned by the server during initialization.",
        "schema": { "type": "string", "minLength": 1 }
      },
      "RequiredMcpSessionId": {
        "name": "Mcp-Session-Id",
        "in": "header",
        "required": true,
        "description": "The opaque session identifier to terminate.",
        "schema": { "type": "string", "minLength": 1 }
      },
      "LastEventId": {
        "name": "Last-Event-ID",
        "in": "header",
        "required": false,
        "description": "The last received SSE event ID, used to resume a disconnected stream when the server supports resumability.",
        "schema": { "type": "string", "minLength": 1 }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "OAuth authentication is required or the bearer token is invalid.",
        "headers": {
          "WWW-Authenticate": {
            "description": "Bearer challenge containing the RFC 9728 resource metadata URL.",
            "schema": { "type": "string" }
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/OAuthError" },
            "example": { "error": "unauthorized", "error_description": "Authentication required" }
          }
        }
      },
      "NotAcceptable": {
        "description": "The endpoint cannot produce any media type allowed by the request's `Accept` header.",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } }
        }
      },
      "InvalidJsonRpc": {
        "description": "The request is not a valid JSON-RPC 2.0 MCP message.",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcError" } }
        }
      },
      "ApiError": {
        "description": "A structured HTTP API error with a stable code and recovery guidance.",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } }
        }
      }
    },
    "schemas": {
      "JsonRpcId": {
        "oneOf": [{ "type": "string" }, { "type": "integer" }]
      },
      "JsonRpcRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["jsonrpc", "id", "method"],
        "properties": {
          "jsonrpc": { "type": "string", "const": "2.0" },
          "id": { "$ref": "#/components/schemas/JsonRpcId" },
          "method": { "type": "string", "minLength": 1, "description": "An MCP method such as `initialize`, `tools/list`, or `tools/call`." },
          "params": { "type": "object", "additionalProperties": true }
        }
      },
      "JsonRpcNotification": {
        "type": "object",
        "additionalProperties": false,
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": { "type": "string", "const": "2.0" },
          "method": { "type": "string", "minLength": 1 },
          "params": { "type": "object", "additionalProperties": true }
        }
      },
      "JsonRpcSuccess": {
        "type": "object",
        "additionalProperties": false,
        "required": ["jsonrpc", "id", "result"],
        "properties": {
          "jsonrpc": { "type": "string", "const": "2.0" },
          "id": { "$ref": "#/components/schemas/JsonRpcId" },
          "result": { "description": "A method-specific, typed MCP result.", "type": "object", "additionalProperties": true }
        }
      },
      "JsonRpcError": {
        "type": "object",
        "additionalProperties": false,
        "required": ["jsonrpc", "error"],
        "properties": {
          "jsonrpc": { "type": "string", "const": "2.0" },
          "id": { "$ref": "#/components/schemas/JsonRpcId" },
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "integer", "description": "A stable JSON-RPC or MCP error code." },
              "message": { "type": "string", "minLength": 1 },
              "data": { "description": "Optional method-specific error details and recovery information." }
            }
          }
        }
      },
      "ApiError": {
        "type": "object",
        "additionalProperties": false,
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": ["code", "message", "resolution_hint"],
            "properties": {
              "code": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$", "description": "A stable, machine-readable error code." },
              "message": { "type": "string", "minLength": 1, "description": "A concise explanation of the failure." },
              "resolution_hint": { "type": "string", "minLength": 1, "description": "A concrete next step an agent can take to recover." },
              "details": { "type": "object", "additionalProperties": true }
            }
          },
          "request_id": { "type": "string", "description": "An optional support correlation identifier." }
        }
      },
      "OAuthError": {
        "type": "object",
        "additionalProperties": true,
        "required": ["error", "error_description"],
        "properties": {
          "error": { "type": "string", "description": "The OAuth error code." },
          "error_description": { "type": "string", "description": "A human-readable explanation." },
          "error_uri": { "type": "string", "format": "uri", "description": "Optional recovery documentation." }
        }
      },
      "ProtectedResourceMetadata": {
        "type": "object",
        "additionalProperties": true,
        "required": ["resource", "authorization_servers"],
        "properties": {
          "resource": { "type": "string", "format": "uri", "const": "https://app.briefhq.ai/mcp" },
          "authorization_servers": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uri" } },
          "bearer_methods_supported": { "type": "array", "items": { "type": "string" } },
          "resource_documentation": { "type": "string", "format": "uri" }
        }
      },
      "AuthorizationServerMetadata": {
        "type": "object",
        "additionalProperties": true,
        "required": ["issuer", "authorization_endpoint", "token_endpoint", "response_types_supported"],
        "properties": {
          "issuer": { "type": "string", "format": "uri" },
          "authorization_endpoint": { "type": "string", "format": "uri" },
          "token_endpoint": { "type": "string", "format": "uri" },
          "device_authorization_endpoint": { "type": "string", "format": "uri" },
          "registration_endpoint": { "type": "string", "format": "uri" },
          "revocation_endpoint": { "type": "string", "format": "uri" },
          "response_types_supported": { "type": "array", "items": { "type": "string" } },
          "grant_types_supported": { "type": "array", "items": { "type": "string" } },
          "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" } },
          "scopes_supported": { "type": "array", "items": { "type": "string" } }
        }
      }
    }
  }
}