MCP Stdio

mcp-stdio

English | 日本語

A stdio↔HTTP MCP gateway that works in both directions — the same binary is both an MCP-over-HTTP client gateway and, via serve mode, a full MCP-over-HTTP server (with an optional embedded OAuth 2.1 Authorization Server), so it can sit on either end of an MCP connection.

📖 New here? Start with the [user guide](https://shigechika.github.io/mcp-stdio/) — task-oriented docs for connecting a client or publishing a server. This README is the full reference.

Overview

Client gateway (default mode) — stdio → HTTP. MCP clients such as Claude Desktop, Claude Code and OpenAI Codex see mcp-stdio as a locally running self-hosted MCP server, while it relays all requests to a remote MCP server with support for various authentication methods:

flowchart BT

A[MCP client Claude / Codex / …] <-- stdio --> B(mcp-stdio) B <== " HTTPS Streamable HTTP / SSE Bearer Token Header OAuth" ==> C[Remote MCP Server] B -. "OAuth 2.1 (PKCE)" .-> D[Authorization Server] D -. callback .-> B style B fill:#4a5,stroke:#333,color:#fff

Bearer tokens, custom headers, and OAuth 2.1 credentials are forwarded to the remote server.

Reverse gateway (`mcp-stdio serve`) — HTTP → stdio. The mirror image: takes a local stdio MCP server (any language, any framework) and exposes it as a Streamable HTTP endpoint, with optional bearer-token or embedded-OAuth-2.1 authentication, per-user backend isolation when OAuth is enabled, and a restart-durable token store — see Reverse gateway: serve mode below. This is how mcp-stdio can stand in for a framework's own HTTP/OAuth hosting layer (e.g. instead of depending on a Python web framework's built-in server for just that part) when the tool definitions themselves already run fine over stdio.

Features

• Both MCP transports supported — Streamable HTTP (current spec, default) and SSE (MCP 2024-11-05 legacy), selectable with --transport. SSE parser follows the WHATWG Server-Sent Events spec.
• OAuth 2.1 client — built-in authorization code flow with PKCE, dynamic client registration, token refresh, and secure token persistence. Implements the full MCP authorization spec at the section level:
• RFC 9728 Protected Resource Metadata
• §3 discovery of authorization servers via /.well-known/oauth-protected-resource
• §3.1 path-aware well-known URL construction for path-based reverse-proxy deployments, with host-root fallback; preserves the resource URL's query component on the constructed metadata URL
• §3.3 resource field validation — warn on mismatch, continue
• §5.1 WWW-Authenticate: Bearer resource_metadata= hint — probes the server before discovery so servers that publish PRM at a non-standard URL are found without well-known path guessing
• RFC 8414 Authorization Server Metadata
• §3.1 well-known URL construction, including path insertion for issuers with path components
• §3.3 issuer validation — reject a cross-origin issuer (AS mix-up guard), warn on a same-origin mismatch (trailing slash / path / case) and continue
• §3 OpenID Connect Discovery 1.0 fallback — when the OAuth well-known 404s, probe /.well-known/openid-configuration (path-append and path-insertion) for ASes that expose only the OIDC form (Auth0, Okta, Azure AD, Google)
• RFC 8707 Resource Indicators
• §2 resource parameter in authorization, token exchange, and refresh requests
• RFC 7636 PKCE
• §4.1–4.2 S256 code_challenge_method with an 86-char code_verifier
• RFC 8628 Device Authorization Grant
• §3.1 device authorization request with resource indicator (RFC 8707)
• §3.4–3.5 token polling with authorization_pending / slow_down (interval +=5 s) / expired_token / access_denied handling
• DCR registers urn:ietf:params:oauth:grant-type:device_code in grant_types (RFC 7591 §2)
• RFC 7591 Dynamic Client Registration
• §3 client registration request; token_endpoint_auth_method chosen from token_endpoint_auth_methods_supported in AS metadata (prefers none → client_secret_post → client_secret_basic)
• §3.2.1 client_secret_expires_at handling — auto re-register on expiry
• application_type: "native" in DCR (RFC 8252 §8.4 / MCP SEP-837): the loopback auth-code and headless device flows are native clients, so the loopback redirect is not rejected as the RFC 7591 default "web"
• Client ID Metadata Documents (MCP 2025-11-25 / draft-ietf-oauth-client-id-metadata-document-00)
• --client-metadata-url presents an operator-hosted HTTPS document URL as client_id, skipping Dynamic Client Registration; honoured when set even if the AS metadata does not (yet) advertise client_id_metadata_document_supported (warns instead of silently falling back), and outranked by a pre-registered client_id (--client-id or MCP_OAUTH_CLIENT_ID) (#60)
• the hosted document's redirect_uris must include mcp-stdio's loopback callback without a port (http://127.0.0.1/callback) — the actual callback binds a fresh ephemeral port every run, and the AS must accept any port for a loopback redirect URI (RFC 8252 §7.3 / §8.4)
• RFC 6749 OAuth 2.0
• §2.3.1 client_secret_basic: Authorization: Basic header with percent-encoded credentials (applied to code exchange, token refresh, and Device Authorization Grant polling)
• RFC 6750 Bearer Token usage
• §2.1 Authorization: Bearer request header
• Works with MCP 2026-07-28 servers — add --protocol-era auto and mcp-stdio asks the server which protocol it speaks and adapts; your MCP client needs no changes. Without the flag nothing changes, so upgrading is safe. mcp-stdio serve answers both old and new clients on the same address automatically — or only the newer ones with --modern-only, and --modern-idle-ttl reclaims idle backends. Newer clients can also hold one connection open and hear when your server's tool, prompt or resource lists change, or when a specific resource they named is updated (mcp-stdio subscribes on their behalf when your server declares resources.subscribe). Verified end to end against python-sdk v2.0.0 in both directions. → Working with MCP 2026-07-28 servers
• Retry with backoff — retries up to 3 times on connection errors; after a transport error that may follow delivery (e.g. a read timeout on a slow tools/call), only known replay-safe methods (read-only or idempotent, such as tools/list or resources/read) are retried, so such an error never re-executes a tools/call
• HTTP 429 / 503 handling — honours Retry-After (delta-seconds or HTTP-date) up to a 60-second cap on both 429 (Too Many Requests) and 503 (Service Unavailable) — the two spec-sanctioned Retry-After carriers (RFC 9110 §10.2.3) — then surfaces the status so the client can decide (cf. modelcontextprotocol/typescript-sdk#1892)
• Auto-pagination (Streamable HTTP transport) — transparently follows nextCursor for tools/list / resources/list / resources/templates/list / prompts/list and merges the pages into one response, so clients that drop pages beyond the first still see the full list (cf. anthropics/claude-code#39586)
• Streaming resilience — streams SSE responses in real time; auto-reconnects on mid-stream disconnect
• Line-separator safety — escapes raw U+2028 / U+2029 (legal in JSON, but JavaScript line terminators) in upstream responses so clients that treat them as line breaks cannot mis-frame the output; lossless (cf. modelcontextprotocol/typescript-sdk#2155)
• Argument normalization — rewrites a tools/call request whose arguments is null to {} so strict servers that reject the null form accept the call; on by default, opt out with --no-normalize-arguments (cf. modelcontextprotocol/typescript-sdk#2012)
• **Mcp-Param-* headers** — against a 2026-07-28 server, mirrors every tool argument the server marks with x-mcp-header into the Mcp-Param-* header the spec requires (python-sdk v2 servers reject a tools/call without it), hides tools whose annotations are invalid, and on a -32020 re-lists the tools once and retries the call; --mcp-param-headers always does the same on an older-protocol session for servers that still require the headers there (GitHub's hosted MCP server), off opts out (#459)
• Cancellation-aware filtering — tracks request ids cancelled via notifications/cancelled on stdin and drops any late upstream response carrying one of those ids before it reaches the client, per the MCP cancellation spec; on by default (60 s TTL), opt out with --no-cancel-filter (cf. anthropics/claude-code#51073)
• SSE in-flight error synthesis — on the legacy SSE transport, replies arrive only on the long-lived GET stream; when that stream drops, requests already POSTed would otherwise hang forever. mcp-stdio tracks the ids in flight on the current stream and synthesizes a JSON-RPC -32000 error for each on a drop — so the client can retry instead of hanging — while auto-reconnecting; cancelled ids are skipped (cf. anthropics/claude-code#60061)
• Session recovery — resets MCP session ID on 404 and retries
• Protocol version header — captures the negotiated protocolVersion from the initialize response and injects MCP-Protocol-Version on every subsequent Streamable HTTP request (MCP spec rev 2025-06-18); servers that enforce the header would otherwise reject post-initialize requests with 400 Bad Request
• Token refresh on 401 — automatically refreshes expired OAuth tokens mid-session (OAuth mode only)
• Re-authorization when the refresh token dies — if the refresh itself is rejected (revoked or expired grant, no refresh token), the relay runs the same interactive sign-in as at startup on a background thread, answers that request with -32002 ("finish signing in, then retry"), and later requests use the new token, with no restart needed. One sign-in at a time: relay processes for the same server wait for each other and reuse the stored token, and a failed attempt starts a 60 s cooldown. On by default with --oauth / --oauth-device; opt out with --no-oauth-reauth (#471)
• Proactive token refresh — a background timer refreshes the OAuth token shortly before it expires (lead time: --oauth-refresh-leeway), so a long-lived session survives gateways that signal token expiry as an HTTP 200 tool-error instead of a transport 401 (e.g. Atlassian's MCP gateway); on by default in OAuth mode, opt out with --no-proactive-refresh (#242)
• Step-up authorization on 403 — on a Bearer error="insufficient_scope" challenge, re-authorizes for the union of the granted and required scopes (RFC 9470 / MCP step-up; cf. anthropics/claude-code#44652)
• Cold-start (`--oauth-eager`) — answers initialize locally and runs the interactive OAuth flow on a background thread, so a 30–180 s browser/SSO/MFA login does not exceed the client's ~60 s initialize timeout. Gated methods return -32002 until login completes, t