proxyMcpRequest.md
MCP server proxy endpoint
Proxies MCP JSON-RPC requests to third-party servers with automatic authentication.
This endpoint supports both regular Streamable HTTP requests and Server-Sent Events (SSE) for real-time MCP protocol communication.
Usage
- JSON-RPC: Send MCP protocol requests as JSON
- SSE Streaming: Use
Accept: text/event-streamfor real-time communication - Session Management: Include
x-mcp-session-idheader for session tracking
Authentication Flow
- User must first connect to the server via
/api/servers/{server_id}/connect - Complete OAuth flow for the third-party service
- Use this endpoint to proxy MCP requests with automatic credential injection
OpenAPI
get /mcp/{mcp_server_name}
openapi: 3.1.0
info:
title: Barndoor Platform 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 Barndoor's
OAuth 2.0 authorization-code 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}.platform.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: Servers
description: Manage MCP server instances
- name: Connections
description: Manage OAuth connections to MCP servers
- name: Policies
description: Manage access control policies for agents and servers
- name: Agents
description: Manage AI agent registrations
- name: MCP Proxy
description: Proxy requests to MCP servers
- name: Identity
description: Retrieve identity information for the authenticated user
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 Streamable HTTP requests and
Server-Sent Events (SSE)
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
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 Barndoor's OAuth 2.0 authorization-code
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.