D2 · Tool Design & MCP › Cluster 5 · MCP Fundamentals

5.3 · Transports (stdio · Streamable HTTP)

How messages move

CONCEPT Two standard transports

The transport layer is how JSON-RPC messages actually travel. The spec defines two standard transports, and clients SHOULD support stdio whenever possible:

🔑 Streamable HTTP supersedes the older HTTP+SSE transport (protocol version 2024-11-05). The spec: "This replaces the HTTP+SSE transport from protocol version 2024-11-05." New remote servers use Streamable HTTP; old two-endpoint HTTP+SSE is deprecated (backward-compat only).

CONCEPT JSON-RPC message framing

Whatever the transport, JSON-RPC messages MUST be UTF-8 encoded. Framing differs per transport:

stdioStreamable HTTP
LocationLocal subprocess (same machine)Remote/independent process
Channelstdin / stdoutHTTP POST (+ optional GET/SSE)
FramingOne message per line, newline-delimited; no embedded newlinesHTTP request/response bodies; SSE events for streams
StreamingSequential messagesOptional SSE stream from server
AuthLocal process trustBearer / API keys / OAuth headers
Clients servedUsually oneMany
⚠️ stdio discipline: the server MUST NOT write anything to stdout that is not a valid MCP message — a stray print() corrupts the stream. Use stderr for logging.
Streamable HTTP security: servers MUST validate the Origin header (DNS-rebinding defense), SHOULD bind to 127.0.0.1 when local, and SHOULD require authentication.

DIAGRAM Local subprocess vs. remote endpoint

sequenceDiagram participant C as Client participant L as Local server (stdio) participant R as Remote server (Streamable HTTP) Note over C,L: stdio — client launches subprocess C->>L: launch subprocess C->>L: write JSON-RPC to stdin L-->>C: write JSON-RPC to stdout L--)C: optional logs on stderr Note over C,R: Streamable HTTP — single MCP endpoint C->>R: POST JSON-RPC (Accept: json + event-stream) alt single response R-->>C: application/json (one object) else server streams R--)C: text/event-stream (SSE messages…) R--)C: SSE: JSON-RPC response end

CODE Registering local (stdio) vs remote (HTTP) servers

Same protocol, two transports. A local server is a command the host launches; a remote server is a URL. With the Claude CLI:

# Local server over stdio — the host launches it as a subprocess
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path

# Remote server over Streamable HTTP — the host connects to a URL
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# In the Messages API MCP connector, remote servers are declared by url:
mcp_servers = [
    { "type": "url",
      "name": "sentry",
      "url": "https://mcp.sentry.dev/mcp",
      "authorization_token": "Bearer <token>" }   # HTTP auth
]

TRADE-OFFS stdio vs. Streamable HTTP

✅ stdio (local)

  • Zero network overhead, lowest latency
  • Simplest trust model — same machine, launched by the host
  • Great for filesystem / local-tool servers; clients SHOULD prefer it

✅ Streamable HTTP (remote)

  • Reachable over the network; one server serves many clients
  • Standard HTTP auth (OAuth / bearer) and optional SSE streaming
  • But: needs Origin validation, TLS, and auth to be safe

EXAM TRAPS

Trap: "SSE is a third transport." → The standalone HTTP+SSE transport is deprecated and superseded by Streamable HTTP (which may itself use SSE to stream). The two current standard transports are stdio and Streamable HTTP.
Trap: "stdio talks over the network." → stdio is a local subprocess over stdin/stdout — no network. Remote = Streamable HTTP.
Trap: Logging to stdout in a stdio server. → stdout must carry only valid MCP messages; logs go to stderr, or they corrupt the JSON-RPC stream.
Trap: "The message format changes with the transport." → It doesn't. JSON-RPC 2.0 (UTF-8) is identical across transports; only framing and connection setup differ.

PRACTICE

Q1 · Which transport for a filesystem server on the user's laptop, and why?

stdio — it's local, so the host launches the server as a subprocess and exchanges JSON-RPC over stdin/stdout with no network overhead. The spec says clients SHOULD prefer stdio when possible.

Q2 · What did Streamable HTTP replace, and what may it use to stream?

It replaced the older HTTP+SSE transport (protocol version 2024-11-05). Streamable HTTP uses HTTP POST for client→server messages and may optionally open a Server-Sent Events (SSE) stream for multiple server→client messages.

Q3 · How are individual JSON-RPC messages framed over stdio?

Newline-delimited, one message per line, UTF-8, with no embedded newlines inside a message. The server must write nothing but valid MCP messages to stdout.