Skip to main content

​
MCP Transport Protocols

Satellite implements three MCP transport protocols for external client communication. Each protocol serves different use cases and client requirements.

​
Transport Overview

ProtocolEndpointMethodUse Case
SSE Transport/sseGETPersistent connections with session management
SSE Messaging/messagePOSTJSON-RPC message sending via established sessions
Streamable HTTP/mcpGET/POSTDirect HTTP communication with optional streaming

​
SSE Transport

​
Connection Establishment

Endpoint: GET /sse Headers:
  • Accept: text/event-stream (required)
  • Cache-Control: no-cache
  • Connection: keep-alive
Response:
  • Content-Type: text/event-stream
  • Session ID and endpoint URL sent as SSE events
  • 30-minute session timeout with automatic cleanup
Example: 
curl -N -H "Accept: text/event-stream" http://localhost:3001/sse
SSE Events: 
event: endpoint
data: {"url": "http://localhost:3001/message?session=abc123..."}

event: heartbeat
data: {"timestamp": "2025-01-09T13:30:00.000Z"}

​
Session Management

  • Session ID: 32-byte cryptographically secure base64url identifier
  • Timeout: 30 minutes of inactivity
  • Activity Tracking: Updated on each message received
  • Cleanup: Automatic removal of expired sessions

​
SSE Messaging

Endpoint: POST /message?session={sessionId} Headers:
  • Content-Type: application/json (required)
Request Body: JSON-RPC 2.0 message 
{
  "jsonrpc": "2.0",
  "id": "req-1",
  "method": "initialize",
  "params": {
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}
Response: Message processing status 
{
  "status": "sent",
  "messageId": "req-1"
}
Status Codes:
  • 200 - Message sent successfully
  • 202 - Message accepted (for notifications)
  • 400 - Invalid JSON-RPC or missing session
  • 404 - Session not found
  • 500 - Internal server error

​
Streamable HTTP Transport

​
GET Endpoint

Endpoint: GET /mcp Headers:
  • Accept: text/event-stream (required for SSE stream)
  • Mcp-Session-Id: {sessionId} (optional)
Response: SSE stream with heartbeat messages

​
POST Endpoint

Endpoint: POST /mcp Headers:
  • Content-Type: application/json (required)
  • Accept: application/json (default) or text/event-stream (streaming)
  • Mcp-Session-Id: {sessionId} (optional)
Request Body: JSON-RPC 2.0 message Response Modes:
  1. Standard JSON: Direct JSON-RPC response
  2. SSE Streaming: Response sent via Server-Sent Events

​
Supported MCP Methods

​
Core Protocol

  • initialize - Initialize MCP session
  • notifications/initialized - Client initialization complete

​
Tools

  • tools/list - List available tools from remote MCP servers
  • tools/call - Execute tools on remote MCP servers
For detailed information about tool discovery and execution, see Tool Discovery Implementation.

​
Resources

  • resources/list - List available resources (returns empty array)
  • resources/templates/list - List resource templates (returns empty array)

​
Prompts

  • prompts/list - List available prompts (returns empty array)

​
Error Handling

​
JSON-RPC Errors

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found: unknown_method"
  },
  "id": "req-1"
}

​
HTTP Errors

{
  "success": false,
  "error": "Session not found"
}

​
Common Error Codes

  • -32600 - Invalid Request
  • -32601 - Method not found
  • -32603 - Internal error
  • -32001 - Session not found (custom)

​
Client Integration

​
MCP Client Configuration

SSE Transport Example: 
{
  "mcpServers": {
    "satellite": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-fetch"],
      "env": {
        "MCP_SERVER_URL": "http://localhost:3001/sse"
      }
    }
  }
}
Direct HTTP Example: 
{
  "mcpServers": {
    "satellite": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-fetch"],
      "env": {
        "MCP_SERVER_URL": "http://localhost:3001/mcp"
      }
    }
  }
}

​
Development Setup

​
Local Testing

  1. Start Satellite: 
    cd services/satellite
npm run dev
  2. Test SSE Connection: 
    curl -N -H "Accept: text/event-stream" http://localhost:3001/sse
  3. Send JSON-RPC Message: 
    curl -X POST "http://localhost:3001/message?session=YOUR_SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{}}'

​
Protocol Selection

Use SSE Transport when:
  • Long-lived connections needed
  • Session state management required
  • Real-time bidirectional communication
Use Streamable HTTP when:
  • Stateless request/response patterns
  • Standard HTTP client libraries
  • Optional streaming responses

​
Security Considerations

  • No Authentication: Current implementation has no security layer
  • Session Isolation: Sessions are isolated by cryptographic session IDs
  • Resource Limits: 30-minute session timeout prevents resource exhaustion
  • CORS Support: Cross-origin requests supported via preflight handling

​
Logging and Monitoring

All transport protocols generate structured logs with:
  • Operation tracking
  • Session management events
  • Error conditions
  • Performance metrics
See Logging Documentation for detailed log format specifications.
⌘I