If you are wiring an MCP server into a client, the transport is the first decision. A common symptom is a server that runs while the client has no idea whether to launch a command or call a URL. The question often appears as "MCP stdio vs SSE," but the current spec adds a third option: Streamable HTTP. Older tutorials point at /sse; newer server docs point at /mcp. Both can be right, depending on which transport the server speaks.
Use stdio for a server that runs on your own machine and serves one local user. Use Streamable HTTP for a remote or shared server. Treat SSE (Server-Sent Events) as a legacy compatibility path: it means the old HTTP+SSE transport from the 2024-11-05 spec, which has been deprecated since 2025-03-26. Do not build a new server on it. As of November 15, 2026, the latest spec listed by the MCP project is 2026-07-28, and the standard transports are stdio and Streamable HTTP (transports spec).
This guide covers what each transport is, how they compare, how to choose, how to configure Claude Code and Cursor, how to migrate from SSE, and what to check when a connection returns 400, 403, 404, or 405. If you are new to the host/client/server model, start with What Is MCP?.
What Each Transport Is
stdio: the client launches a local process
With stdio, the client starts the MCP server as a subprocess. The server reads JSON-RPC messages from standard input and writes JSON-RPC messages to standard output (stdio spec).
Each message is one JSON-RPC (a JSON-based remote procedure call format) request, notification, or response. Messages are newline-delimited and cannot contain embedded newlines. Standard output is the wire: the server must not write anything to stdout that is not a valid MCP message. Logs, debug output, and errors go to stderr. The client may capture, forward, or ignore stderr, and it should not assume every stderr line means failure.
stdio has no HTTP header layer. Protocol version and client capabilities travel inside the JSON-RPC message body. To cancel an in-flight request, the client sends a notifications/cancelled notification. There is no per-request stream to close, because stdio uses one shared bidirectional channel. Shutdown starts by closing the child process's input stream and waiting for it to exit; if it does not exit in a reasonable time, the client terminates it, typically escalating from SIGTERM to SIGKILL on POSIX systems. Servers should exit when stdin closes or reads return EOF. If the server exits unexpectedly, the client should restart it. The protocol is stateless, so in-flight requests are lost and can be retried against the new process.
This is the right fit for local files, Git, local databases, and scripts that need direct system access. Claude Code's docs describe stdio servers as ideal for tools that need direct system access or custom scripts (Claude Code docs). The boundary is equally clear: the server and client run on the same machine, usually for one user, and the server process lives and dies with the client session.
Streamable HTTP: one endpoint, one POST per message
Streamable HTTP was introduced in the 2025-03-26 spec as a replacement for the 2024-11-05 HTTP+SSE transport (Streamable HTTP spec). In the current revision, the server exposes one MCP endpoint that accepts POST. The client sends every JSON-RPC request or notification as its own HTTP POST. The server answers each request with a single JSON object or with an SSE stream scoped to that request.
An SSE response can carry request-related notifications such as notifications/progress before the final response. The server cannot send independent requests on that stream. The final response should terminate the stream. To cancel a request, the client closes that response stream; the server should stop work and send nothing further. A client that wants long-lived list-change or resource-update notifications sends a subscriptions/listen request, and the server keeps a long-lived POST response stream open for the notification types the client opted into. Server-to-client interactions such as sampling, elicitation, and roots are returned as input requests inside a result, and the client retries the original request with the requested input. The spec calls this Multi Round-Trip Requests (MRTR).
The 2026-07-28 revision changed several things that older tutorials still assume. It removed protocol-level sessions, so there is no Mcp-Session-Id. It removed the standalone GET stream. Cross-call state is now carried by a server-minted handle (an identifier the server creates) passed as an ordinary tool argument. It also removed SSE resumability and message redelivery: Last-Event-ID is no longer supported, and a broken response stream loses the in-flight request, so the client must re-issue it with a new request ID (2026-07-28 changes).
Streamable HTTP fits remote services, team-shared servers, and multi-user or multi-device deployments. The server runs independently, can sit behind a reverse proxy or load balancer, and can use OAuth or other authentication. The cost is that you now own the network layer: TLS, proxy behavior, auth, version negotiation, and header validation.
SSE: the old two-endpoint HTTP+SSE transport
The word SSE is overloaded. It helps to separate two things.
The first is the HTTP+SSE transport from the 2024-11-05 spec. The server provides two endpoints: an SSE endpoint where the client connects to receive server messages, and a regular HTTP POST endpoint where the client sends messages. When the client connects, the server must send an endpoint event containing the URI for subsequent client messages. After that, server messages arrive as SSE message events with JSON data (2024-11-05 transports). This is the transport this article calls SSE.
The second is an SSE stream inside Streamable HTTP. When handling a POST request, a Streamable HTTP server may choose to stream notifications and the final response as text/event-stream. That is part of the current transport, not the old two-endpoint transport.
The timeline has three nodes. 2024-11-05 defined stdio and HTTP+SSE; 2025-03-26 introduced Streamable HTTP and deprecated HTTP+SSE; 2026-07-28 removed the GET stream, protocol-level sessions, and resumability from Streamable HTTP. The deprecated-features registry lists HTTP+SSE as Deprecated with Streamable HTTP as the migration path. Its earliest removal is tied to SEP-2596 reaching Final, not to a published date (deprecated features). Deprecated means it is still in the spec, but new implementations should not adopt it and existing ones should migrate before removal. It is not Removed.
Comparison Table
| Dimension | stdio | SSE (old HTTP+SSE) | Streamable HTTP |
|---|---|---|---|
| Server location | Local machine | Local or remote | Local or remote |
| Who starts the server | Client launches a subprocess | Server runs independently | Server runs independently |
| Client config | command + args | URL to an SSE endpoint | URL to the MCP endpoint |
| Message channel | stdin / stdout, newline-delimited JSON-RPC | SSE stream for server messages, separate POST endpoint for client messages | One POST per message, JSON or request-scoped SSE response |
| Multi-user | Usually one local user | Can serve multiple users | Can serve multiple users |
| Auth | Manual (local process) | Usually OAuth or a token | Usually OAuth or a token |
| Reconnect | Client restarts the process and retries in-flight requests | No replay defined in the old spec | No replay in the current revision; client re-issues the request |
| Spec status | Current standard transport | Deprecated, scheduled for removal | Current standard transport |
| Typical use | Local files, Git, local database, scripts | Legacy servers that only expose /sse | Team services, cloud APIs, multi-user systems |
The multi-user and auth rows follow Cursor's transport table: stdio is local, managed by the client, single-user, and manually configured; SSE and Streamable HTTP can be local or remote, deployed as a server, multi-user, and OAuth-based (Cursor docs). The reconnect row follows the specs: the old SSE transport defines no replay, and current Streamable HTTP explicitly does not support Last-Event-ID. The table is for selection, not a performance ranking.
How to Choose
Use stdio when the server is local and personal. If only you use it, it only needs files or services on this machine, and it does not need to be shared, stdio is the simpler option. There is no port, no TLS, and no OAuth flow in the client config. Claude Code also lets you put -- before the server command so the client does not parse the server's own flags (Claude Code docs).
Use Streamable HTTP when the server is shared or remote. If the server runs on a network, serves a team or multiple clients, or needs OAuth, reverse-proxy support, and centralized logs, use Streamable HTTP. Claude Code's docs call HTTP the recommended option for remote MCP servers and describe it as widely supported for cloud services. Cursor's table gives both SSE and Streamable HTTP multi-user and OAuth support, but SSE is deprecated, so there is no reason to start a new project there.
Use SSE only for compatibility. Some older services expose only an SSE endpoint. A client can still connect to them. Claude Code can try Streamable HTTP first and switch to SSE when the server does not accept it; the automatic switch requires Claude Code v2.1.265 or later. On an earlier version, or to force SSE, pass --transport sse. Treat this as a bridge, not a destination.
Do not look for a session header. The current spec has no protocol-level session and no Mcp-Session-Id. If a server needs state across calls, it should mint an explicit handle and pass it as a normal tool argument. Solutions built on cookies, a session header, or connection-scoped state do not match the current spec.
Use subscriptions/listen for long-lived notifications. Streamable HTTP opens a long-lived POST response stream for the notification types the client opts into. stdio can also deliver notifications, over its shared channel. The difference is deployment shape, not whether push is possible.
Do not expect replay. The 2026-07-28 revision removed SSE event IDs and Last-Event-ID. If the response stream breaks, the in-flight request is lost. The client must re-issue it with a new request ID. Treating Streamable HTTP as a reliable queue leads to recovery logic that cannot work.
Start with stdio when configuration cost matters. No port, certificate, or client-to-server auth is needed. The tradeoff is that the server stays local and cannot be shared.
Configuration
Claude Code
Claude Code has one command shape per transport (official docs):
# Remote Streamable HTTP
claude mcp add --transport http notion https://mcp.notion.com/mcp
# Legacy SSE endpoint
claude mcp add --transport sse asana https://mcp.asana.com/sse
# Local stdio
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
-- npx -y airtable-mcp-server
In .mcp.json, ~/.claude.json, or claude mcp add-json, the type field accepts streamable-http as an alias for http. A server's documented config can be pasted as-is.
A JSON entry with a url but no type is treated as a stdio server. Claude Code skips it and reports:
MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry
Add "type": "http" or "type": "sse".
For stdio, everything after -- goes to the server untouched. --env accepts multiple KEY=value pairs, but do not put the server name directly after --env; it will be read as another pair and rejected. Put another option such as --transport stdio between them.
Cursor
In Cursor's mcp.json, stdio servers use command and remote servers use url (official docs). Project config lives at .cursor/mcp.json; global config lives at ~/.cursor/mcp.json.
A minimal stdio entry:
{
"mcpServers": {
"local-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-server"],
"env": {
"API_KEY": "value"
}
}
}
}
Cursor's field table marks type and command as required for stdio, with args, env, and envFile optional. A remote entry uses url, plus headers when the server needs auth:
{
"mcpServers": {
"remote-server": {
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
}
}
}
}
${env:NAME} reads from the environment. Do not commit a token directly into the config.
MCP Inspector
When a connection fails, test the server by itself in the Inspector first (Inspector recipes). A stdio server is a process the Inspector spawns, so the command goes on the command line:
mcp-inspector node build/index.js -- --verbose --config /etc/myserver.conf
Only arguments after -- reach the server. For stdio, the server's stderr appears in the Console tab. That is the first place to look when the connection fails without a visible reason.
For HTTP and SSE servers:
mcp-inspector --server-url https://api.example.com/mcp --transport http \
--header "X-Tenant: acme"
--transport accepts http (Streamable HTTP) and sse. The Inspector's protocol era defaults to legacy; set modern or auto in Server Settings, or pass --protocol-era legacy|auto|modern, to exercise 2026-07-28 behavior. If the Inspector connects but your client does not, compare the transport type and protocol era on both sides first.
Server checklist
For a stdio server: write only valid MCP messages to stdout, log to stderr, and exit when stdin reaches EOF.
For a Streamable HTTP server: expose one POST endpoint; validate Origin and return 403 when it is invalid; bind to 127.0.0.1 for local use; clients must send Accept with both application/json and text/event-stream; return 202 with no body for an accepted notification; return JSON or an SSE stream for a request; on SSE responses, include X-Accel-Buffering: no and periodic : keep-alive comments on long-lived streams; validate MCP-Protocol-Version, Mcp-Method, and Mcp-Name.
For a legacy SSE server: keep the SSE and POST endpoints. If old clients still need it, host both alongside the new MCP endpoint. The spec says combining the old POST endpoint with the new MCP endpoint is possible but adds unnecessary complexity, so keep them separate when you can.
Migrating From SSE
HTTP+SSE has been deprecated since 2025-03-26. The current spec classifies it as Deprecated, with Streamable HTTP as the migration path (deprecated features).
Server side
Add a POST MCP endpoint, such as /mcp. Answer each request with JSON or a request-scoped SSE stream. Apply the header, Origin, status-code, and keep-alive rules from the server checklist.
If old clients still connect, keep the old SSE and POST endpoints running next to the new endpoint. New clients use /mcp; old clients keep using /sse. The spec documents this compatibility arrangement. It also notes that merging the old POST endpoint and the new MCP endpoint adds complexity.
Remove the old assumptions while you migrate. Do not rely on Mcp-Session-Id. Do not serve a standalone GET SSE stream. Do not use Last-Event-ID for replay. A 2026-07-28 server should return 405 for GET or DELETE, ignore an incoming Mcp-Session-Id without minting or echoing one, and ignore Last-Event-ID because streams are not resumable.
Client side
Once the server supports the new endpoint, change the URL from /sse to /mcp and set the transport to Streamable HTTP. If the client is talking to a server that has not upgraded, it first sends a POST. If the server returns 400, 404, or 405 and the body is not a recognized modern JSON-RPC error, the client can GET the same URL, wait for the first endpoint event, conclude that the server uses the old HTTP+SSE transport, and continue on that transport. This fallback order is in the spec. Client libraries usually implement it; if you write your own, do not skip the body check.
In Claude Code, use --transport http for both new servers and servers that only expose SSE. Version 2.1.265 and later try HTTP first and switch to SSE automatically. Older versions, or a direct SSE connection, use --transport sse.
From older Streamable HTTP revisions
Streamable HTTP from 2025-03-26 through 2025-11-25 had a different shape. It allowed a session via Mcp-Session-Id, a standalone GET SSE stream, server-initiated requests on SSE streams, and resumability via Last-Event-ID. The 2026-07-28 revision removed all of these.
When a server upgrades, return 405 for GET or DELETE from an old client, ignore the old session header, and ignore Last-Event-ID. When a client upgrades, stop waiting for a GET stream, stop depending on a session ID, and re-issue requests after a disconnect. On a version mismatch, the server returns 400 with UnsupportedProtocolVersionError and lists the versions it supports. A client can call server/discover first to learn the supported versions and pick one both sides understand.
SDK migration notes
The TypeScript SDK v2 implements the 2026-07-28 spec. Its @modelcontextprotocol/server package no longer ships the server-side SSE transport; SSEServerTransport moved to @modelcontextprotocol/server-legacy/sse. New code should use Streamable HTTP. Import the legacy package only when you must serve old HTTP+SSE clients (TS SDK troubleshooting).
The Python SDK v2 README says it supports stdio, Streamable HTTP, and SSE. uv run mcp run server.py --transport streamable-http serves a server over Streamable HTTP, and a client given a URL uses Streamable HTTP by default (Python SDK).
Common Errors and Fixes
The table below uses errors and behaviors documented by the official sources. Do not force an unrelated failure into one of these rows.
| Symptom / error | Likely cause | What to check and fix |
|---|---|---|
| stdio server does not appear or fails to start | Wrong command path, invalid JSON config, missing environment variable, unexpected working directory | Run the server command manually in a terminal; use absolute paths; check env; read the client log and the server's stderr. The debugging guide notes that the working directory may be undefined and that stdio servers inherit only a limited set of environment variables |
SyntaxError: Unexpected token ... is not valid JSON | The server or a dependency wrote a log line to stdout and broke the newline-delimited JSON-RPC wire | Move logs to stderr. With the TypeScript SDK, use console.error, not console.log. Keep stdout for protocol messages only |
MCP server "<name>" has a "url" but no "type" | A Claude Code JSON entry has a url but no type, so it is read as a stdio server | Add "type": "http" or "type": "sse". streamable-http is accepted as an alias for http |
SSE stream disconnected: TypeError: terminated | An idle connection was closed by the client or an intermediary | Check proxy buffering and idle timeouts. The spec recommends X-Accel-Buffering: no and keep-alive comments; the TypeScript SDK emits a : keepalive comment every 15 seconds by default and exposes keepAliveMs |
400 UnsupportedProtocolVersionError (-32022) | No mutually supported protocol version | Read the supported list in the error; call server/discover; retry with a version both sides support |
400 HeaderMismatch (-32020) | A required header is missing or does not match the body; Mcp-Name is missing on a request that requires it; a proxy rewrote a header | Check MCP-Protocol-Version, Mcp-Method, and Mcp-Name against the body. Mcp-Name is required for tools/call, resources/read, and prompts/get |
404 with JSON-RPC code -32601 | The server does not implement the method | Check the method and version. If the 404 body is not a JSON-RPC error, the URL may be an old HTTP+SSE server without the new endpoint, and the client may need the legacy fallback |
403 Forbidden | Invalid Origin triggered DNS-rebinding protection (an attack that tricks a browser into reaching local services), or an auth or IP policy rejected the request | Check the Origin header; bind local servers to 127.0.0.1; for remote servers, check the token, OAuth scope, and IP allowlist |
| 401 or 403 authentication failure | No auth configured, expired token, insufficient scope, or revoked key | Configure OAuth or a bearer token; confirm the token was issued for this server; reauthorize or replace the key |
| GET or DELETE returns 405 | A 2026-07-28 server does not support the old GET stream or DELETE session | This is expected. Upgrade the client to use POST, or run a server that also supports the older revision |
Module '"@modelcontextprotocol/server"' has no exported member 'SSEServerTransport' | TypeScript SDK v2 moved the server-side SSE transport to the legacy package | Use Streamable HTTP for new code; import from @modelcontextprotocol/server-legacy/sse only for old clients |
Troubleshoot in five passes, starting with the transport and ending with the network path.
First, confirm the transport type. Is the config a command or a url? Does the URL end in /mcp or /sse? Is type set to http, sse, or stdio? A wrong transport type makes every later check irrelevant.
Second, test the server alone. For stdio, launch the command in the Inspector and read stderr in the Console. For HTTP or SSE, connect with --server-url and --transport. The Inspector's protocol era defaults to legacy; set it to modern or auto to test 2026-07-28 behavior.
Third, check the version and metadata. Every current request must carry io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities in _meta; a missing field is rejected with -32602. If the server needs a capability the request did not declare, it returns MissingRequiredClientCapabilityError (-32021). On HTTP, also confirm that the MCP-Protocol-Version header matches the body.
Fourth, inspect HTTP headers and status codes. A minimal tools/list probe built from the 2026-07-28 spec looks like this:
curl -sS -D - https://example.com/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2026-07-28' \
-H 'Mcp-Method: tools/list' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'
Read the status and body. For 400, decide whether it is a version error or a header mismatch. For 403, check Origin and auth. For 404, read the JSON-RPC error code. For 405, check whether the request used GET or DELETE. A text/event-stream response means the server chose streaming, not that the request failed.
Fifth, check the network path. A reverse proxy can buffer SSE, rewrite headers, or close streams early. A TLS terminator can drop Mcp-* headers. Use browser DevTools or curl -D - to see the headers actually sent and the status actually returned. A Streamable HTTP server's stderr is not captured by the client, so collect server logs yourself or use OpenTelemetry (debugging guide).
FAQ
Is SSE deprecated?
Yes. The old HTTP+SSE transport has been deprecated since the 2025-03-26 spec, and the current spec classifies it as Deprecated. It remains in the spec, but new implementations should not adopt it and existing ones should migrate to Streamable HTTP. The registry ties the earliest removal to SEP-2596 reaching Final and does not publish a date.
Why does Streamable HTTP still use SSE?
SSE is a response format there. A server handling a POST request may stream notifications and the final response as text/event-stream. That is different from the old two-endpoint HTTP+SSE transport. Seeing text/event-stream does not mean you are on the deprecated transport.
What if the server only exposes /sse?
A client can still connect over SSE. Claude Code can use --transport http and, in v2.1.265 or later, fall back to SSE automatically; older versions or a direct connection use --transport sse. At the same time, plan the server upgrade to a /mcp endpoint and keep the old endpoint only for clients that have not moved.
Should I still use Mcp-Session-Id?
No, not with the 2026-07-28 spec. There is no protocol-level session and no such header. It existed in Streamable HTTP revisions 2025-03-26 through 2025-11-25. For cross-call state, use a server-minted handle passed as a tool argument.
Which transport should a team use?
Streamable HTTP. It supports remote deployment, multiple users, and OAuth. SSE can also serve multiple users, but it is deprecated and is a poor starting point for new work. stdio is for local, single-user setups.
Which transport should I use for local files, Git, or a database?
stdio. The client launches a local process, which uses local permissions and needs no network port.
Can a stdio server log to stdout?
No. stdout is the protocol wire and may contain only valid MCP messages. Logs go to stderr, which the client may capture or ignore. A stray console.log in a stdio server commonly shows up as a JSON parse error in the client.
Why does the Inspector connect when my client does not?
Compare the transport type and protocol era first. The Inspector defaults to legacy, while the client may be using 2026-07-28, or the reverse. Then check the client's type, url, command, environment variables, and working directory. Read both the client log and the server log instead of relying on the Inspector result alone.
Bottom Line
For MCP transports, stdio vs SSE vs Streamable HTTP comes down to deployment shape: stdio for a local, single-user server; Streamable HTTP for a remote or shared server; SSE only to keep a legacy server working while you migrate. When you migrate, change the endpoint first, then remove the old assumptions about sessions, GET streams, and replay. When you debug, confirm the transport and protocol version before you chase headers, status codes, proxies, and auth.