proxySSERequest.md
SSE Server Proxy Endpoint
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-streamcommunication - Real-time Events: Custom event types and data streaming
- 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 for real-time event streaming with automatic credential injection
OpenAPI
get /sse/{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:
/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 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.