openapi: 3.1.0
info:
  title: Barndoor Platform Agents MCP Proxy API
  version: 1.0.0
  description: 'REST API for the Barndoor Platform - manage MCP servers, OAuth connections, and proxy MCP requests.


    ## Authentication


    All endpoints require a JWT Bearer token obtained through Auth0 OAuth 2.0 flow with PKCE.

    The SDK handles the OAuth flow automatically using interactive login.


    ## MCP Integration


    The `/mcp/{mcp_server_name}` endpoints provide streaming proxy access to third-party MCP servers

    (Salesforce, Notion, Slack, etc.) with automatic authentication and session management.

    '
  contact:
    name: Barndoor Support
    url: https://barndoor.ai
servers:
- url: https://{organization_id}.platform.barndoor.ai
  description: Trial (Production)
  variables:
    organization_id:
      description: Your organization identifier
      default: your-org
- url: https://{organization_id}.mcp.barndoor.ai
  description: Enterprise (Production)
  variables:
    organization_id:
      description: Your organization identifier
      default: your-org
- url: https://{organization_id}.platform.barndooruat.com
  description: Enterprise (Production)
  variables:
    organization_id:
      description: Your organization identifier
      default: your-org
- url: https://{organization_id}.platform.barndoordev.com
  description: Enterprise (Production)
  variables:
    organization_id:
      description: Your organization identifier
      default: your-org
security:
- BearerAuth: []
tags:
- name: MCP Proxy
  description: Proxy requests to MCP servers
paths:
  /mcp/{mcp_server_name}:
    get:
      tags:
      - MCP Proxy
      summary: MCP Server Proxy Endpoint
      description: 'Proxies MCP JSON-RPC requests to third-party servers with automatic authentication.


        This endpoint supports both regular HTTP requests and Server-Sent Events (SSE) streaming

        for real-time MCP protocol communication.


        ## Usage


        - **JSON-RPC**: Send MCP protocol requests as JSON

        - **SSE Streaming**: Use `Accept: text/event-stream` for real-time communication

        - **Session Management**: Include `x-mcp-session-id` header for session tracking


        ## Authentication Flow


        1. User must first connect to the server via `/api/servers/{server_id}/connect`

        2. Complete OAuth flow for the third-party service

        3. Use this endpoint to proxy MCP requests with automatic credential injection

        '
      operationId: proxyMcpRequest
      parameters:
      - name: mcp_server_name
        in: path
        required: true
        description: MCP server name identifier
        schema:
          type: string
          pattern: ^[a-z0-9-]+$
        example: salesforce
      - name: x-mcp-session-id
        in: header
        required: false
        description: MCP session identifier for request tracking
        schema:
          type: string
        example: sess_1234567890abcdef
      requestBody:
        required: false
        description: MCP JSON-RPC request payload
        content:
          application/json:
            schema:
              type: object
              description: MCP JSON-RPC 2.0 request
              properties:
                jsonrpc:
                  type: string
                  enum:
                  - '2.0'
                  description: JSON-RPC version
                method:
                  type: string
                  description: MCP method name
                  example: tools/list
                params:
                  type: object
                  description: Method parameters
                  additionalProperties: true
                id:
                  oneOf:
                  - type: string
                  - type: number
                  description: Request identifier
              required:
              - jsonrpc
              - method
              example:
                jsonrpc: '2.0'
                method: tools/list
                params: {}
                id: 1
      responses:
        '200':
          description: MCP response or SSE stream
          content:
            application/json:
              schema:
                type: object
                description: MCP JSON-RPC 2.0 response
                properties:
                  jsonrpc:
                    type: string
                    enum:
                    - '2.0'
                  result:
                    type: object
                    description: Method result
                    additionalProperties: true
                  error:
                    type: object
                    description: Error object if method failed
                    properties:
                      code:
                        type: integer
                      message:
                        type: string
                      data:
                        type: object
                        additionalProperties: true
                  id:
                    oneOf:
                    - type: string
                    - type: number
                    description: Request identifier
                required:
                - jsonrpc
                - id
                example:
                  jsonrpc: '2.0'
                  result:
                    tools:
                    - name: get_accounts
                      description: Get Salesforce accounts
                      parameters:
                        type: object
                        properties:
                          limit:
                            type: integer
                            description: Maximum number of accounts
                  id: 1
            text/event-stream:
              schema:
                type: string
                description: 'Server-Sent Events stream for real-time MCP communication.


                  Each event contains a JSON-RPC message with event metadata.


                  Example events:

                  ```

                  data: {"jsonrpc": "2.0", "method": "notifications/initialized", "params": {}}


                  data: {"jsonrpc": "2.0", "result": {"tools": [...]}, "id": 1}

                  ```

                  '
              example: 'data: {"jsonrpc": "2.0", "method": "notifications/initialized", "params": {}}


                data: {"jsonrpc": "2.0", "result": {"tools": []}, "id": 1}

                '
        '401':
          description: Unauthorized - invalid or missing JWT token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - server not connected or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: ServerNotConnected
                message: Server 'salesforce' is not connected. Please initiate connection first.
        '404':
          description: Server not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Bad Gateway - upstream server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: UpstreamError
                message: Failed to connect to Salesforce API
  /sse/{mcp_server_name}:
    get:
      tags:
      - MCP Proxy
      summary: SSE Server Proxy Endpoint
      description: 'Server-Sent Events proxy endpoint for real-time streaming communication with third-party servers.


        This endpoint provides dedicated SSE streaming capabilities separate from the MCP protocol,

        allowing for custom event streaming and real-time data flows.


        ## Usage


        - **SSE Streaming**: Optimized for `text/event-stream` communication

        - **Real-time Events**: Custom event types and data streaming

        - **Session Management**: Include `x-mcp-session-id` header for session tracking


        ## Authentication Flow


        1. User must first connect to the server via `/api/servers/{server_id}/connect`

        2. Complete OAuth flow for the third-party service

        3. Use this endpoint for real-time event streaming with automatic credential injection

        '
      operationId: proxySSERequest
      parameters:
      - name: mcp_server_name
        in: path
        required: true
        description: MCP server name identifier
        schema:
          type: string
          pattern: ^[a-z0-9-]+$
        example: salesforce
      - name: x-mcp-session-id
        in: header
        required: false
        description: MCP session identifier for request tracking
        schema:
          type: string
        example: sess_1234567890abcdef
      requestBody:
        required: false
        description: Optional request payload for SSE initialization
        content:
          application/json:
            schema:
              type: object
              description: SSE initialization parameters
              properties:
                event_types:
                  type: array
                  items:
                    type: string
                  description: Types of events to subscribe to
                  example:
                  - data_update
                  - status_change
                filters:
                  type: object
                  description: Event filtering parameters
                  additionalProperties: true
                  example:
                    object_type: Account
                    limit: 100
              example:
                event_types:
                - data_update
                - status_change
                filters:
                  object_type: Account
                  limit: 100
      responses:
        '200':
          description: SSE event stream
          content:
            text/event-stream:
              schema:
                type: string
                description: 'Server-Sent Events stream for real-time communication.


                  Events follow the SSE format with optional event types and data payloads.


                  Example events:

                  ```

                  event: connected

                  data: {"status": "ready", "timestamp": "2024-01-01T00:00:00Z"}


                  event: data_update

                  data: {"type": "Account", "id": "123", "changes": {...}}


                  event: error

                  data: {"error": "rate_limit", "message": "Rate limit exceeded"}

                  ```

                  '
              example: 'event: connected

                data: {"status": "ready", "timestamp": "2024-01-01T00:00:00Z"}


                event: data_update

                data: {"type": "Account", "id": "123", "name": "Acme Corp"}


                event: status_change

                data: {"status": "disconnected", "reason": "timeout"}

                '
            application/json:
              schema:
                type: object
                description: Fallback JSON response if SSE not supported
                properties:
                  status:
                    type: string
                    example: streaming_not_supported
                  message:
                    type: string
                    example: Client does not support SSE, use /mcp endpoint instead
        '401':
          description: Unauthorized - invalid or missing JWT token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - server not connected or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: ServerNotConnected
                message: Server 'salesforce' is not connected. Please initiate connection first.
        '404':
          description: Server not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Bad Gateway - upstream server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: UpstreamError
                message: Failed to connect to Salesforce streaming API
components:
  schemas:
    Error:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
          description: Error type identifier
          example: ServerNotFound
        message:
          type: string
          description: Human-readable error message
          example: Server with ID '123' not found
        details:
          type: object
          description: Additional error details
          additionalProperties: true
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT token obtained through Auth0 OAuth 2.0 flow with PKCE.


        The token should be included in the Authorization header:

        `Authorization: Bearer <your-jwt-token>`


        Use the Barndoor SDK''s `loginInteractive()` function to obtain tokens automatically.

        '
    HTTPBearer:
      type: http
      scheme: bearer