MCP Transport Protocols - DeployStack - Enterprise Control Plane for MCP

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:

Standard JSON: Direct JSON-RPC response
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:

When a client opens an SSE connection (GET /mcp), the session is registered
Every 30 seconds, the service sends a ping comment to all active connections
The ping data keeps the TCP connection alive through proxy timeouts
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

Configuration indicates OAuth: Server config includes requires_oauth: true
Token retrieval: Satellite requests user’s tokens from backend
Header injection: Tokens added to Authorization header
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:

Base headers (Content-Type, User-Agent, MCP-Protocol-Version)
Server configuration headers (from config.headers)
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

Start Satellite:
cd services/satellite npm run dev

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.

​Transport Overview

​MCP SDK Implementation

​Session Management

​Streamable HTTP Transport

​GET Endpoint

​POST Endpoint

​SSE Keep-Alive Ping

​Supported MCP Methods

​Core Protocol

​Tools

​Resources

​Prompts

​OAuth Token Injection for HTTP/SSE Transports

​How It Works

​Header Merging Priority

​Example Header Merge

​Error Handling

​JSON-RPC Errors

​HTTP Errors

​Common Error Codes

​Client Integration

​MCP Client Configuration

​Development Setup

​Local Testing

​Protocol Features

​Security Considerations

​Logging and Monitoring

Transport Overview

MCP SDK Implementation

Session Management

Streamable HTTP Transport

GET Endpoint

POST Endpoint

SSE Keep-Alive Ping

Supported MCP Methods

Core Protocol

Tools

Resources

Prompts

OAuth Token Injection for HTTP/SSE Transports

How It Works

Header Merging Priority

Example Header Merge

Error Handling

JSON-RPC Errors

HTTP Errors

Common Error Codes

Client Integration

MCP Client Configuration

Development Setup

Local Testing

Protocol Features

Security Considerations

Logging and Monitoring