stdio vs Streamable HTTP: Choosing and Sharing a Factory
Module 4 — Transports & Deployment
MCP servers can speak two primary transports. The same tool/resource/prompt registration logic works for both — the difference is how the host reaches the server and how long an instance lives.

Left: local stdio (host spawns the process). Right: remote Streamable HTTP (many clients share one endpoint). Bottom: one factory produces a fresh McpServer for each connection or request.

stdio vs Streamable HTTP: Choosing and Sharing a Factory
When to Use Each Transport
Aspect | stdio | Streamable HTTP |
|---|---|---|
Deployment | Local process (IDE, CLI, Inspector) | Remote endpoint (cloud, multi-user) |
Clients | One host owns the child process | Many clients share the endpoint |
Latency | Lowest (no network) | Network hop |
Auth | None needed (local trust) | Bearer / OAuth typical |
Scaling | One process per client | Horizontal (stateless by default) |
Protocol era | Both (factory decides) | Both (default dual-era) |
Rule of thumb: If the server lives on the user's machine and only that user uses it → stdio. If it lives on a server and others (or cloud agents) reach it → Streamable HTTP.
You can expose both from the same codebase.
Never register tools on a long-lived shared instance. Always use a factory that returns a fresh McpServer:
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod/v4';
export function createServer() {
const server = new McpServer({ name: 'notes', version: '1.0.0' });
server.registerTool(
'add-note',
{
description: 'Append a note',
inputSchema: z.object({ text: z.string() })
},
async ({ text }) => ({
content: [{ type: 'text', text: `Saved: ${text}` }]
})
);
return server;
}This factory is the single source of truth. Both transports call it.
Serving over stdio
import { serveStdio } from '@modelcontextprotocol/server/stdio';
import { createServer } from './server.js';
const handle = serveStdio(createServer);
console.error('notes server listening on stdio');serveStdio owns the StdioServerTransport and calls your factory once per connection.
Log only with console.error. stdout is the JSON-RPC channel; any console.log corrupts the stream.
The process waits on stdin until a host connects.
On client close (stdin EOF) the transport shuts itself down. Release any keep-alive handles (timers, pools) on server.server.onclose.
Coming from v1: serveStdio(factory) replaces new StdioServerTransport() + server.connect().
Serving over Streamable HTTP
import { createMcpHandler } from '@modelcontextprotocol/server';
import { createServer } from './server.js';
export const handler = createMcpHandler(createServer);createMcpHandler returns a web-standard { fetch, close, notify, bus } object. The factory runs once per HTTP request — a fresh instance serves every request and the handler holds nothing between them. This is the modern (2026-07-28) default and is inherently stateless.
Complete Side-by-Side Entry Points
stdio.ts
#!/usr/bin/env node
import { serveStdio } from '@modelcontextprotocol/server/stdio';
import { createServer } from './server.js';
void serveStdio(createServer);
console.error('notes MCP server running on stdio');http.ts (Node, minimal)
import { createServer as createHttpServer } from 'node:http';
import { toNodeHandler, localhostHostValidation, localhostOriginValidation } from '@modelcontextprotocol/node';
import { createMcpHandler } from '@modelcontextprotocol/server';
import { createServer } from './server.js';
const handler = createMcpHandler(createServer);
const nodeHandler = toNodeHandler(handler);
const validateHost = localhostHostValidation();
const validateOrigin = localhostOriginValidation();
createHttpServer((req, res) => {
if (!validateHost(req, res) || !validateOrigin(req, res)) return;
void nodeHandler(req, res);
}).listen(3000, '127.0.0.1', () => {
console.error('notes MCP server on http://127.0.0.1:3000/mcp');
});The same createServer factory powers both. Next articles show framework adapters (Express, Hono, Fastify, Workers) and production hardening.
Official Anchors
Get new posts by Nelson Lin
Subscribe to receive email notifications when a new article is published.