Skip to main content
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

ProtocolEndpointMethodUse CaseImplementation
Streamable HTTP/mcpPOSTStandard JSON-RPC communicationOfficial MCP SDK
SSE Streaming/mcpGETServer-sent events for real-time updatesOfficial MCP SDK
Session Management/mcpDELETESession terminationOfficial 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

​
SSE Keep-Alive Ping

When satellites are deployed behind reverse proxies (Cloudflare, nginx), idle SSE connections can timeout after 60-100 seconds, causing 502 Bad Gateway errors for MCP clients. Solution: The satellite includes an SsePingService that sends periodic SSE comments to keep connections alive:
  • Ping interval: Every 30 seconds
  • Ping format: : ping\n\n (SSE comment, ignored by clients)
  • Automatic cleanup: Connections are removed when closed
How it works:
  1. When a client opens an SSE connection (GET /mcp), the session is registered
  2. Every 30 seconds, the service sends a ping comment to all active connections
  3. The ping data keeps the TCP connection alive through proxy timeouts
  4. When the connection closes, it’s automatically unregistered
Implementation files:
  • services/satellite/src/services/sse-ping-service.ts - Ping service
  • services/satellite/src/core/mcp-server-wrapper.ts - Connection registration
This ensures MCP clients (Cursor, VS Code, Claude.ai) maintain stable connections even during extended idle periods when deployed in production environments behind proxies.

​
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 from connected MCP servers
  • resources/templates/list - List resource templates from connected MCP servers
  • resources/read - Read resource content (proxied on-demand to origin server)
_meta Preservation: Resource metadata including _meta fields is preserved through the proxy for MCP Apps support. Resource content is never cached — always proxied on-demand to the origin MCP server.

​
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.