MCP Transport Protocols

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

Transport Overview

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.