> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deploystack.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```typescript theme={null}
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](/development/satellite/tool-discovery).

### 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)

<Info>
  **\_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.
</Info>

### 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](/development/satellite/mcp-server-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**:

```json theme={null}
{
  "headers": {
    "X-API-Key": "team_secret_key"
  }
}
```

**OAuth tokens**:

```json theme={null}
{
  "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

```json theme={null}
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found: unknown_method"
  },
  "id": "req-1"
}
```

### HTTP Errors

```json theme={null}
{
  "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:**

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

**VS Code Configuration:**

```json theme={null}
{
  "servers": {
    "deploystack-satellite": {
      "url": "http://localhost:3001/mcp",
      "type": "http"
    }
  },
  "inputs": []
}
```

## Development Setup

### Local Testing

1. **Start Satellite:**
   ```bash theme={null}
   cd services/satellite
   npm run dev
   ```

2. **Test MCP Connection:**
   ```bash theme={null}
   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](/development/satellite/logging) for detailed log format specifications.