MCP Transport Protocols

Official MCP SDK transport implementation for external client integration

Satellite uses the official @modelcontextprotocol/sdk to provide MCP client communication. This ensures full protocol compliance and works with all MCP clients including VS Code, Claude, and MCP Inspector.

Transport Overview

Protocol	Endpoint	Method	Use Case	Implementation
Streamable HTTP	/mcp	POST	Standard JSON-RPC communication	Official MCP SDK
SSE Streaming	/mcp	GET	Server-sent events for real-time updates	Official MCP SDK
Session Management	/mcp	DELETE	Session termination	Official MCP SDK

MCP SDK Implementation

Satellite leverages the official MCP TypeScript SDK for all transport operations:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';

const server = new Server({
  name: 'deploystack-satellite',
  version: '1.0.0'
});

Session Management

The SDK provides automatic session management with:

• Session ID: Cryptographically secure identifiers
• Timeout: Configurable session timeouts
• Activity Tracking: Automatic session activity updates
• Cleanup: Built-in session cleanup and resource management

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)

OAuth Token Injection for HTTP/SSE Transports

When MCP servers require OAuth authentication (Notion, Box, Linear), the satellite automatically injects user OAuth tokens into HTTP requests.

How It Works

1. Configuration indicates OAuth: Server config includes requires_oauth: true
2. Token retrieval: Satellite requests user’s tokens from backend
3. Header injection: Tokens added to Authorization header
4. Request forwarding: Full request sent to MCP server with credentials

For complete implementation details, see OAuth Token Injection.

Header Merging Priority

When building HTTP requests to OAuth MCP servers, headers are merged in this order:

1. Base headers (Content-Type, User-Agent, MCP-Protocol-Version)
2. Server configuration headers (from config.headers)
3. OAuth Authorization header (from backend token retrieval)

Later headers override earlier ones if keys conflict.

Example Header Merge

Team configuration:

{
  "headers": {
    "X-API-Key": "team_secret_key"
  }
}

OAuth tokens:

{
  "access_token": "ya29.a0AfB_byABC123...",
  "token_type": "Bearer"
}

Final headers sent to MCP server:

Content-Type: application/json
MCP-Protocol-Version: 1.0
X-API-Key: team_secret_key
Authorization: Bearer ya29.a0AfB_byABC123...

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

Standard Configuration:

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

VS Code Configuration:

{
  "servers": {
    "deploystack-satellite": {
      "url": "http://localhost:3001/mcp",
      "type": "http"
    }
  },
  "inputs": []
}

Development Setup

Local Testing

1. Start Satellite:

   cd services/satellite
   npm run dev
   

2. Test MCP Connection:

   curl -X POST "http://localhost:3001/mcp" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{}}'
   

Protocol Features

The official MCP SDK provides:

• Automatic Session Management: Sessions created and managed transparently
• Standard Protocol Compliance: Full MCP specification 2025-03-26 support
• Flexible Transport Options: JSON and SSE streaming responses
• Built-in Error Handling: Standard JSON-RPC error 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.