MCP stdio Transport — For Claude Desktop, Claude Code, Local Agents

What it is

MCP stdio transport connects a Model Context Protocol server to a client — Claude Desktop, Claude Code, or a local agent script — by piping newline-delimited JSON-RPC 2.0 messages over the process's standard input and standard output. The client spawns the server as a child process; the server reads requests from stdin, writes responses to stdout, and sends every log line or debug message exclusively to stderr. That boundary is not a style preference, it is load-bearing: a single stray print statement or console log that lands on stdout corrupts the JSON-RPC frame and hangs or crashes the session outright. Every server author's first line of defence is routing all diagnostic output to stderr from the very first line of code.

Why it matters

• Claude Desktop and Claude Code both default to stdio because the OS handles process isolation and authentication is implicit — zero network config to manage.
• Switch to HTTP only when the server must be shared across clients/machines, is stateful independent of one client, targets a container with no child-process spawning, or needs fine-grained TLS/bearer auth.
• A common mistake is defaulting to HTTP for "production feel" on a personal agent toolbox, losing stdio's simplicity for no reason.

Key points

• Stdio transport — host launches server as child process; JSON-RPC 2.0 messages newline-delimited over stdin/stdout.
• Trust model — OS process boundary is the security boundary; host launching the server is trusted by the user.
• Use cases — Claude Desktop, Claude Code, Cursor, Continue, any local IDE-agent; one developer's productivity loop.
• Logging discipline — stderr only; writing to stdout corrupts the JSON-RPC stream and disconnects the host.
• Single-client by construction — migrate to Streamable HTTP (C227) the moment more than one operator must use the server.
• No OAuth layer, by specification design (spec 2026-07-28) — stdio implementations SHOULD NOT attempt to follow the HTTP authorization model at all; credentials come from the environment (the mcpServers env block), not a token flow.
• Extensions are transport-independent — Elicitation and the Tasks extension (C225, C227) work over stdio exactly as over Streamable HTTP; a local server can still pause mid-call to ask the user something or return a durable taskId for a slow local job.

Terms used on this page

stdio transport

MCP wire format where the host launches the server as a child process and exchanges JSON-RPC 2.0 messages over its stdin/stdout; simplest deployment mode.

claude_desktop_config.json

Per-user JSON config file where Claude Desktop registers MCP servers; lists command + args + env for each server.

JSON-RPC 2.0

Lightweight remote-procedure-call protocol over JSON; the wire encoding for every MCP message regardless of transport.

Single-client constraint

Architectural property of stdio: one host process owns the server's I/O streams; second client requires the HTTP transport.

stdio and authorization (spec 2026-07-28)

The current specification states explicitly that implementations using an stdio transport SHOULD NOT follow the HTTP authorization specification and should instead retrieve credentials from the environment — formalizing what this card already treats as the trust model.

Elicitation over stdio

The client feature (spec 2026-07-28, see C225) that lets a server pause mid-task to request one more piece of information from the user; it is transport-independent, so a stdio server can use it exactly as an HTTP one can, provided the host declares support at initialize.

Extension negotiation

The general MCP mechanism (spec 2026-07-28) by which a client and server each declare, at initialize / server/discover, which optional extensions (Tasks, Elicitation-adjacent features, Skills) they support; applies identically whether the transport underneath is stdio or Streamable HTTP.

Sources

1. Model Context Protocol specification — stdio transport
2. Anthropic — MCP TypeScript SDK + stdio examples
3. Anthropic — Claude Desktop MCP configuration reference
4. Model Context Protocol — stdio transport specification (2026-07-28)
5. Model Context Protocol — Authorization specification (2026-07-28), stdio exemption
6. Model Context Protocol — Tasks extension overview (spec 2026-07-28)
7. Model Context Protocol — Extensions client-matrix (host support tracker)
8. Model Context Protocol — Build a server, develop guide (spec 2026-07-28)
9. Model Context Protocol — Security Best Practices tutorial (spec 2026-07-28)
10. Model Context Protocol — Specification versioning documentation (2026-07-28)
11. Model Context Protocol — Local Server Security (stdio trust model, isolation, credentials and egress)
12. Model Context Protocol — Debugging (stdio logging, Claude Desktop logs and common issues)
13. Model Context Protocol — Connect to local MCP servers (Claude Desktop configuration and approval flow)
14. AWS Machine Learning Blog — Add secure Web Search to Claude Desktop with Amazon Bedrock AgentCore (remote managed MCP server with JWT auth, 2 Oct 2026)
15. Google Cloud Blog — Empower your agents with the Google Cloud CLI remote MCP server (CLI behind remote MCP instead of local binaries, 1 Oct 2026)
16. NVIDIA Technical Blog — Add Runtime Controls to AI Agents with NVIDIA OpenShell (runtime permission enforcement outside the agent, 28 Sep 2026)