Documentation
Documentation
https://docs.barndoor.ai/api-reference/introduction
Authentication
https://docs.barndoor.ai/api-reference/introduction
OpenAPI Specification
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