MCP transports: stdio, SSE, and streamable HTTP

The three names, and which one you want

A transport is only the pipe the JSON-RPC messages travel down. It has nothing to do with what a server can do, and picking the wrong one produces a connection failure rather than a degraded server, which is at least an honest failure mode.

stdio, and why it is still the default

The client spawns the server as a child process and speaks newline-delimited JSON-RPC over its stdin and stdout. Anything on stderr is treated as logging. The server must not write anything to stdout that is not a valid MCP message, which is the single most common way a home-grown stdio server breaks: one stray print() during startup corrupts the stream.

# Claude Code
claude mcp add playwright -- npx @playwright/mcp@latest

# Codex
codex mcp add context7 -- npx -y @upstash/context7-mcp

stdio wins on latency, needs no auth layer, and keeps data on your machine. It loses when the server should be shared, when it needs to survive your editor restarting, or when the vendor would rather run it themselves. That is the entire case for the remote transports.

MCP SSE: what the SSE transport was, and why it went away

The original remote transport, introduced in protocol version 2024-11-05, used two endpoints. The client opened a long-lived GET to something like https://example.com/sse, the server replied with an endpoint event naming a second URL, and every client-to-server message was POSTed there while every server-to-client message came back down the original stream.

It worked, and it had three problems that a single-endpoint design does not.

• It requires a long-lived connection for everything. A server that only answers requests still had to hold an open stream per client, which serverless platforms and ordinary load balancers are both bad at.
• Two endpoints means two places to get auth, CORS, and routing wrong. Most reported "SSE MCP server" failures were the POST endpoint being unreachable while the stream itself connected fine, which reads as a mysterious hang rather than an error.
• Resumption was ill-defined. Dropping the stream dropped the session, and there was no agreed way to pick it back up.

Streamable HTTP, and what the 2026-07-28 revision changed

One endpoint, for example https://example.com/mcp, accepting POST. Each JSON-RPC message is a new POST. The server answers with either application/json for a single result, or text/event-stream when it wants to stream progress notifications before the result. That is the whole design, and it is why a plain request-response server no longer needs any streaming machinery at all.

The current revision, released 28 July 2026, took the design considerably further in the same direction.

• Protocol-level sessions are gone. The Mcp-Session-Id header was removed. Servers needing cross-call state mint an explicit handle and pass it as an ordinary tool argument.
• The initialize handshake is gone. Every request carries its protocol version and client capabilities in _meta, and a new server/discover RPC advertises what a server supports.
• The GET endpoint is gone. Server-to-client change notifications now ride a single long-lived subscriptions/listen POST stream that the client opts into.
• SSE resumability is gone. Last-Event-ID and SSE event ids were removed. A broken response stream loses the in-flight request and the client must reissue it with a new request id.

Configuring each transport, per client

Claude Code

# streamable HTTP, the default choice
claude mcp add --transport http notion https://mcp.notion.com/mcp

# SSE, for a vendor that exposes nothing else
claude mcp add --transport sse asana https://mcp.asana.com/sse

# with an auth header, either transport
claude mcp add --transport http secure https://api.example.com/mcp \
  --header "Authorization: Bearer $TOKEN"

# local stdio
claude mcp add playwright -- npx @playwright/mcp@latest

Claude Code prints a deprecation warning on --transport sse and points you at HTTP. In JSON, whether that is .mcp.json, ~/.claude.json, or claude mcp add-json, the type field takes http, streamable-http as an alias for it, sse, or ws.

Cursor

{
  "mcpServers": {
    "modern": {
      "url": "https://mcp.example.com/mcp",
      "type": "http"
    },
    "legacy": {
      "url": "https://mcp.example.com/sse",
      "type": "sse"
    },
    "local": {
      "command": "npx",
      "args": ["-y", "some-mcp-server"]
    }
  }
}

Codex

[mcp_servers.context7]
command = "npx"
args    = ["-y", "@upstash/context7-mcp"]

[mcp_servers.figma]
url                  = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

codex mcp add linear --url https://mcp.linear.app/mcp \
  --bearer-token-env-var LINEAR_TOKEN

codex mcp login linear     # for servers behind OAuth
codex mcp list

Migrating an SSE MCP server to streamable HTTP

If you run the server, the migration is smaller than it looks, because both transports can live side by side while clients catch up.

If you only consume servers, migration is one line: change --transport sse to --transport http and the URL from /sse to /mcp, then check claude mcp list. If the vendor has not shipped a streamable HTTP endpoint, staying on SSE is correct for now, and the twelve-month policy window means it is not urgent.

The connection errors, and what each one means

Two operational details worth knowing before you debug anything deeper. Claude Code reconnects a dropped HTTP or SSE server automatically with exponential backoff, up to five attempts, so an intermittent server shows as pending rather than failed. And remote servers carry a per-request timer covering the time to first response byte, defaulting to 60 seconds, which is separate from the per-tool-call wall clock. A server that is merely slow to start streaming will trip the first timer while looking healthy by the second.

Questions people ask

Keep reading

Continue through MCP for Claude Code with DeepWiki MCP: ask any public GitHub repo a question.