stdio vs Streamable HTTP: Choosing and Sharing a Factory

By — 7+ years building ML / AI agent systems, founder of agent-engineering.dev & sandx.ai.
Published: Last updated:
mcp transportsstdio vs httpstreamable httpshared factorymcp server 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.

MCP Transports: stdio vs Streamable HTTP

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.

be3D0.jpg

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.

The Shared Factory Pattern

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.