mcp-transport-stdio-http

MCP Transports — stdio vs Streamable HTTP

Pick the right transport and the rest of your server design follows.

When to Use

• Starting a new MCP server and choosing a transport
• Migrating from deprecated SSE transport to Streamable HTTP
• Debugging "connection dropped" or "session expired" errors
• Scaling a remote MCP server horizontally

Transport Matrix

Transport	Use when	Pros	Cons
stdio	Local tools, CLI integrations, single-user	Zero network, trusted process, simplest	Only local; one client per server process
Streamable HTTP	Remote multi-user servers	Bidirectional, resumable, load-balanceable	More complex; requires session layer
SSE (legacy)	Existing deployments	—	Deprecated; migrate to Streamable HTTP

stdio Transport

Server reads from stdin, writes JSON-RPC to stdout, logs to stderr. Client spawns the process.

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
const transport = new StdioServerTransport();
await server.connect(transport);

Critical rule: never write non-JSON to stdout. console.log breaks the protocol. Use console.error for logs.

// BAD
console.log("Server started"); // corrupts protocol stream

// GOOD
console.error("Server started");

Streamable HTTP Transport (current spec)

Single HTTP endpoint handles all methods. Server pushes messages via SSE on long-lived GET, receives messages via POST, supports resumable sessions via Mcp-Session-Id header.

Server (TypeScript)

import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import express from "express";

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

const transports = new Map<string, StreamableHTTPServerTransport>();

app.all("/mcp", async (req, res) => {
  const sessionId = req.headers["mcp-session-id"] as string | undefined;
  let transport = sessionId ? transports.get(sessionId) : undefined;

  if (!transport) {
    transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: () => crypto.randomUUID(),
      onsessioninitialized: (id) => transports.set(id, transport!),
    });
    await server.connect(transport);
  }

  await transport.handleRequest(req, res, req.body);
});

app.listen(3000);