Transport Deep Dive

// Complete stdio server bootstrap — exactly what you built in Day 7
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new McpServer({ name: 'my-server', version: '1.0.0' });

// ... register tools, resources, prompts ...

const transport = new StdioServerTransport();
await server.connect(transport);
// Server is now listening — process stays alive until stdin closesstdio bootstrap

// src/http-server.ts — Full HTTP + SSE server with Express
import express from 'express';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

const app = express();
app.use(express.json());

// Session store: sessionId → transport instance
const sessions = new Map<string, SSEServerTransport>();

// ── SSE endpoint — client opens this first ────────────────────────────────
app.get('/sse', async (req, res) => {
  // Set SSE headers
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');
  res.setHeader('X-Accel-Buffering', 'no'); // disable nginx buffering

  const transport = new SSEServerTransport('/message', res);
  const sessionId = transport.sessionId;
  sessions.set(sessionId, transport);

  const server = new McpServer({ name: 'my-http-server', version: '1.0.0' });
  // register tools, resources, prompts on `server`...
  await server.connect(transport);

  req.on('close', () => {
    sessions.delete(sessionId);
    console.error(`[SSE] Session ${sessionId} disconnected`);
  });
});

// ── POST endpoint — all client → server messages ──────────────────────────
app.post('/message', async (req, res) => {
  const sessionId = req.query.sessionId as string;
  const transport = sessions.get(sessionId);

  if (!transport) {
    res.status(404).json({ error: 'Session not found' });
    return;
  }
  await transport.handlePostMessage(req, res, req.body);
});

// ── Health check ──────────────────────────────────────────────────────────
app.get('/health', (_req, res) => {
  res.json({ status: 'ok', sessions: sessions.size });
});

const PORT = process.env.PORT ?? 3000;
app.listen(PORT, () => console.error(`[HTTP MCP] listening on :${PORT}`));src/http-server.ts

// src/ws-server.ts — WebSocket MCP server with the 'ws' library
import { WebSocketServer, WebSocket } from 'ws';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { WebSocketServerTransport } from '@modelcontextprotocol/sdk/server/websocket.js';

const wss = new WebSocketServer({ port: 3001 });

wss.on('connection', async (ws: WebSocket, req) => {
  console.error(`[WS] New connection from ${req.socket.remoteAddress}`);

  // Each connection gets its own McpServer instance
  const server = new McpServer({ name: 'my-ws-server', version: '1.0.0' });
  // register tools, resources, prompts...

  const transport = new WebSocketServerTransport(ws);
  await server.connect(transport);

  ws.on('close', () => console.error('[WS] Client disconnected'));
  ws.on('error', (err) => console.error('[WS] Error:', err));
});

console.error('[WS MCP] WebSocket server on ws://localhost:3001');src/ws-server.ts

// The complete Transport interface from @modelcontextprotocol/sdk
import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';

// ── In-process transport pair — perfect for unit testing ─────────────────
// Creates two linked transports: messages sent on A arrive on B, and vice versa.
export function createInProcessTransportPair(): [Transport, Transport] {
  let aHandler: ((msg: JSONRPCMessage) => void) | undefined;
  let bHandler: ((msg: JSONRPCMessage) => void) | undefined;

  const a: Transport = {
    start: async () => {},
    close: async () => { a.onclose?.(); b.onclose?.(); },
    send: async (msg) => { bHandler?.(msg); },           // A sends → B receives
    set onmessage(fn) { aHandler = fn; },
    get onmessage() { return aHandler; },
    onerror: undefined,
    onclose: undefined,
  };

  const b: Transport = {
    start: async () => {},
    close: async () => { a.onclose?.(); b.onclose?.(); },
    send: async (msg) => { aHandler?.(msg); },           // B sends → A receives
    set onmessage(fn) { bHandler = fn; },
    get onmessage() { return bHandler; },
    onerror: undefined,
    onclose: undefined,
  };

  return [a, b];
}

// Usage in tests:
// const [clientTransport, serverTransport] = createInProcessTransportPair();
// await mcpServer.connect(serverTransport);
// await mcpClient.connect(clientTransport);
// Now test client.callTool(...) against a real server with no networkin-process transport

// ── stdio: env-var secrets ────────────────────────────────────────────────
// Secrets are injected via the claude_desktop_config.json "env" block
// and read with process.env inside the server. Never hardcode.
const GITHUB_TOKEN = process.env.GITHUB_TOKEN;
if (!GITHUB_TOKEN) throw new Error('GITHUB_TOKEN env var is required');

// ── HTTP+SSE: Bearer token middleware ─────────────────────────────────────
import type { Request, Response, NextFunction } from 'express';

function requireAuth(req: Request, res: Response, next: NextFunction) {
  const auth = req.headers.authorization ?? '';
  const token = auth.startsWith('Bearer ') ? auth.slice(7) : null;

  if (!token || token !== process.env.MCP_SECRET_TOKEN) {
    res.status(401).json({ error: 'Unauthorized' });
    return;
  }
  next();
}

// Apply to both endpoints
app.get('/sse',     requireAuth, sseHandler);
app.post('/message', requireAuth, postHandler);

// ── WebSocket: token in the upgrade request ───────────────────────────────
wss.on('connection', (ws, req) => {
  // Option A: token in query string (simpler, less secure)
  const url = new URL(req.url ?? '/', 'ws://localhost');
  const token = url.searchParams.get('token');

  // Option B: token in Sec-WebSocket-Protocol header (more standard)
  const protocols = req.headers['sec-websocket-protocol'] ?? '';
  const bearerToken = protocols.split(',').find(p => p.trim().startsWith('token-'))?.slice(6);

  if (!token && !bearerToken) {
    ws.close(1008, 'Unauthorized'); // 1008 = Policy Violation
    return;
  }
  // ... proceed with authenticated connection
});auth patterns

// Production nginx config — TLS termination + proxy to Node MCP server
server {
    listen 443 ssl http2;
    server_name mcp.yourdomain.com;

    ssl_certificate     /etc/letsencrypt/live/mcp.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.yourdomain.com/privkey.pem;

    # SSE requires disabled buffering + increased timeouts
    location /sse {
        proxy_pass         http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection '';          # must be empty for SSE
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_buffering    off;                    # critical for SSE
        proxy_cache        off;
        proxy_read_timeout 86400s;                 # 24h — keep SSE alive
        chunked_transfer_encoding on;
    }

    # POST messages — normal proxy
    location /message {
        proxy_pass       http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        client_max_body_size 1m;
    }
}nginx.conf

// WebSocket heartbeat + graceful shutdown pattern
const PING_INTERVAL = 30_000;
const PONG_TIMEOUT  = 10_000;

wss.on('connection', (ws) => {
  let isAlive = true;
  ws.on('pong', () => { isAlive = true; });

  const pingTimer = setInterval(() => {
    if (!isAlive) {
      console.error('[WS] Heartbeat timeout — terminating');
      ws.terminate();
      return;
    }
    isAlive = false;
    ws.ping();
  }, PING_INTERVAL);

  ws.on('close', () => clearInterval(pingTimer));
});

// Graceful shutdown on SIGTERM (e.g., Kubernetes rolling deploy)
process.on('SIGTERM', async () => {
  console.error('[shutdown] SIGTERM received — draining connections');
  wss.clients.forEach(ws => ws.close(1001, 'Server shutting down'));
  await new Promise(r => wss.close(r));
  process.exit(0);
});resilience patterns

// Scaling tip: share session state in Redis so any server can handle
// any POST /message — you don't need hard sticky sessions for POST,
// only for the SSE connection itself.

import { createClient } from 'redis';

const redis = createClient({ url: process.env.REDIS_URL });
await redis.connect();

// On SSE connect — store session metadata
await redis.setEx(`session:${sessionId}`, 86400, JSON.stringify({
  connectedAt: Date.now(),
  serverId: process.env.SERVER_ID,
}));

// On POST /message — look up session to confirm it exists
const meta = await redis.get(`session:${sessionId}`);
if (!meta) { res.status(404).json({ error: 'Session expired' }); return; }

// On SSE disconnect — clean up
await redis.del(`session:${sessionId}`);redis session sharing