MCP Transports: stdio vs Streamable HTTP
On this page
Learning Objective
Compare MCP's two standard transports, explain how messages are framed on each, choose the right one for local and remote servers, and apply the security rules that each transport requires.
Concept Explanation
MCP separates what is said, the JSON-RPC messages, from how it travels, the transport. The specification defines two standard transports. Choosing between them is mostly a question of where the server runs and who else needs to reach it.
With stdio, the host launches the server as a child process and the two exchange newline-delimited JSON-RPC messages over the process's standard input and output. Standard error is free for logs, which is where a stdio server must send them, because anything printed to standard output that is not a protocol message corrupts the stream. stdio is simple, fast and private: there is no network port, the server inherits only what the host gives it, and it lives exactly as long as the host needs it. It is the natural choice for local tools such as file access, git, or a database on the developer's machine. Its limits are that the server runs on the user's machine with the user's permissions, and it cannot be shared between users.
Streamable HTTP runs the server as an independent web service with a single endpoint, conventionally /mcp. The client sends each JSON-RPC message as an HTTP POST. The server answers either with a plain JSON body or, when it wants to send progress or log notifications before the final result, with a text/event-stream response whose events carry those messages and then the result. Since 2026-07-28 every POST must also carry Mcp-Method and Mcp-Name headers that mirror the method and tool or resource name, so gateways and firewalls can route and filter without parsing the body. Because there are no sessions, any replica can handle any request.
For notifications that are not tied to a request, such as "the tool list changed", the client opens a subscriptions/listen request, a long-lived POST whose response stream carries only the notification types it opted into. This replaced the older standalone GET stream. If a response stream breaks mid-request, the client simply reissues the request with a new id; the 2026 revision removed stream resumption.
Remote servers face the open network, so the transport comes with security duties. Servers must validate the Origin header to block DNS rebinding attacks, in which a malicious web page tricks a browser into talking to a server on localhost. Servers meant for local use should bind to 127.0.0.1, not all interfaces. Remote servers should require authorization (Day 22) and use HTTPS. The older HTTP plus SSE transport from 2024 is deprecated; new servers should only offer Streamable HTTP.
| Aspect | stdio | Streamable HTTP |
|---|---|---|
| Where the server runs | Child process of the host | Independent web service |
| Framing | Newline-delimited JSON on stdin and stdout | HTTP POST per message; JSON or SSE response |
| Logging | stderr only | Normal server logs, OpenTelemetry |
| Sharing | One user, one machine | Many users and hosts |
| Auth | Inherits the user's environment | OAuth 2.1 bearer tokens |
| Key security rule | Never print non-protocol text to stdout | Validate Origin, bind localhost when local, use HTTPS |
Worked Example: One TypeScript Server, Both Transports
With the v2 TypeScript SDK, the server definition is independent of the transport. This file serves stdio by default and Streamable HTTP when started with --http, using the stateless pattern of a fresh server and transport per request and the SDK's host and origin guards.
import { createServer } from 'node:http';
import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import { NodeStreamableHTTPServerTransport, localhostHostValidation,
localhostOriginValidation } from '@modelcontextprotocol/node';
import * as z from 'zod/v4';
function buildServer(): McpServer {
const server = new McpServer({ name: 'status', version: '1.0.0' });
server.registerTool('service_health', {
description: 'Report whether a service is healthy. Services: api, worker, db.',
inputSchema: z.object({ service: z.enum(['api', 'worker', 'db']) }),
annotations: { readOnlyHint: true },
}, async ({ service }) => ({ content: [{ type: 'text', text: `${service}: healthy` }] }));
return server;
}
if (process.argv.includes('--http')) {
const validHost = localhostHostValidation();
const validOrigin = localhostOriginValidation(); // blocks DNS rebinding from web pages
createServer(async (req, res) => {
if (req.url !== '/mcp') { res.writeHead(404).end(); return; }
if (!validHost(req, res) || !validOrigin(req, res)) return;
const server = buildServer(); // stateless: one per request
const transport = new NodeStreamableHTTPServerTransport({ sessionIdGenerator: undefined });
res.on('close', () => { transport.close(); server.close(); });
await server.connect(transport);
await transport.handleRequest(req, res);
}).listen(3000, '127.0.0.1'); // local only until auth is added
console.error('MCP over HTTP on http://127.0.0.1:3000/mcp');
} else {
await buildServer().connect(new StdioServerTransport());
console.error('MCP over stdio'); // stderr, never stdout
}Both status messages go to standard error. On stdio, a console.log to standard output would inject non-JSON text into the protocol stream and break the client.
Real-World Examples
- Most developer-tool servers, such as the reference filesystem and git servers, ship as stdio packages run with npx or uvx, while SaaS vendors such as GitHub, Stripe, Linear and Atlassian host remote Streamable HTTP servers that users connect to with OAuth.
- Researchers have repeatedly found local MCP and other developer servers exposed to DNS rebinding because they bound to all interfaces without checking Origin, which is why the specification requires Origin validation for HTTP servers.
Review Questions & Answers
Standard output carries the protocol's JSON-RPC messages. Any other text there corrupts the message stream and breaks the client, so logs must go to standard error.
When it wants to send messages such as progress or log notifications related to the request before the final result. The stream carries those messages and then the result.
DNS rebinding, where a malicious web page makes the user's browser send requests to a server running on localhost or the local network. Checking Origin rejects requests that come from untrusted web pages.
It sends a subscriptions/listen request, a long-lived POST whose response stream carries only the notification types the client opted into, tagged with a subscription id.