Skip to content

Reference

CLI Flags

Basic Usage

mcp-stdio [OPTIONS] URL

Arguments:
  URL                    Remote MCP server URL

Authentication

Flag Environment Variable Description
--bearer-token TOKEN MCP_BEARER_TOKEN Static bearer token for authentication
--oauth — Enable OAuth 2.1 authentication (browser flow)
--oauth-device — Enable OAuth 2.1 Device Authorization Grant (RFC 8628, headless)
--client-id ID MCP_OAUTH_CLIENT_ID Pre-registered OAuth client ID (skips Dynamic Client Registration)
--client-metadata-url URL — HTTPS URL of a Client ID Metadata Document to use as client_id instead of DCR
--oauth-scope SCOPE — OAuth scope(s) to request, space-separated in one value (e.g. "openid offline_access"). When the server grants a scope that differs from the one previously granted (e.g. a downgrade), mcp-stdio logs authorization server granted scope: … to stderr; unchanged refreshes stay quiet
--oauth-use-id-token — Present the OIDC id_token as the Bearer credential instead of access_token (AWS Bedrock / Cognito)
--oauth-eager — Cold-start: answer initialize locally and run interactive OAuth in the background, so a long login does not exceed the client's ~60 s timeout
--oauth-refresh-leeway SECONDS MCP_OAUTH_REFRESH_LEEWAY Proactively refresh tokens this many seconds before expiry (default: 60)
--no-proactive-refresh — Disable the background timer that refreshes the OAuth token before it expires
--no-oauth-reauth — Do not sign in again in the background when a 401's refresh is rejected (revoked or expired grant, no refresh token). By default the relay runs the interactive flow on a background thread, answers that request with -32002, and later requests use the new token (#471)
--oauth-timeout SECONDS — Seconds to wait for the interactive OAuth flow (browser callback / device-code confirmation) before giving up (default: 120)
--no-resource-indicator — Omit the RFC 8707 resource parameter from all OAuth requests. Required for some authorization servers that reject it (e.g. Microsoft Entra ID with api:// scopes)
--oauth-resource URI — Send this exact RFC 8707 resource value on every OAuth request instead of the server-URL-derived one. Required for AS that demand a specific resource identifier, e.g. Entra ID's App ID URI api://<app-id>. Persisted in the token store. Mutually exclusive with --no-resource-indicator

Transport

Flag Default Description
--transport {streamable-http,sse} streamable-http Transport type (Streamable HTTP is current MCP spec; SSE is legacy 2024-11-05)
--timeout-connect SEC 10 Connection timeout in seconds
--timeout-read SEC 120 Read timeout in seconds
--sse-read-timeout SEC 300 Idle read timeout on the SSE GET stream (SSE transport only; 0 disables)
--no-tcp-keepalive — Disable TCP keepalive on the HTTP socket
--max-message-size BYTES 10 MiB Cap on a single upstream response body (JSON or cumulative SSE stream) buffered before parsing; 0 disables the cap. Also sends Accept-Encoding: identity by default (#416, #417); -H 'Accept-Encoding: gzip'/deflate opts back in and decodes through a genuinely size-bounded decompressor (#418) — any other negotiated coding (stacked, or one this relay has no bounded decoder for) needs --max-message-size 0 to be accepted at all. Also applies to this relay's own OAuth HTTP traffic (discovery, DCR, token exchange/refresh, device-flow polling) — an authorization server is exactly as untrusted a peer as the MCP server itself (#419)

Newer MCP servers (2026-07-28)

Only needed when the server you connect to was built for the newer MCP spec. See Working with MCP 2026-07-28 servers.

Flag Default Description
--protocol-era {legacy,modern,auto} legacy How to talk to the remote server. legacy behaves exactly as before; auto asks the server once at startup and picks for you; modern skips the question when you already know it is a newer server. Ignored (with a warning) on --transport sse
--listen-read-timeout SEC 300 How long to wait on a quiet notification connection before reconnecting. Only used against newer servers. Unlike --sse-read-timeout, 0 is not allowed — the connection always needs a timeout. Silently ignored on --transport sse
--mcp-param-headers {modern,always,off} modern Mirror tool arguments a server marks with x-mcp-header into Mcp-Param-* headers, hide tools with invalid annotations, and recover from a -32020 by re-listing once and retrying the call once. modern does this against newer servers only; always also on an older-protocol session, for servers that require the headers there (GitHub's hosted MCP server); off disables all of it (#459)

What --check does and does not cover

--check confirms the server is reachable either way — if the older handshake is refused it retries the way a newer server expects, so a newer-only server still reports ✓. It is a connectivity check, though: it does not exercise the rest of the newer behaviour, such as the long-lived notification connection.

Headers & Proxies

Flag Description
-H, --header 'Key: Value' Custom header (repeatable); headers are included on every request
— Proxies are honored via standard HTTP_PROXY, HTTPS_PROXY, NO_PROXY env vars

Behavior

Flag Description
--no-cancel-filter Disable the cancel-aware response filter (drops late responses for ids cancelled via notifications/cancelled)
--no-normalize-arguments Disable rewriting a tools/call request's arguments:null to {} before forwarding

Utilities

Flag Description
--check Check connection and exit. Runs the whole path once: discovery, OAuth login (if applicable), token exchange, and an MCP initialize round-trip
-V, --version Show version
-h, --help Show help

Run mcp-stdio --help for full per-flag detail including platform notes and issue references.


Serve Mode

mcp-stdio serve exposes a local stdio MCP server as a Streamable HTTP endpoint. See Publish your stdio server for detailed setup.

Basic Usage

mcp-stdio serve [OPTIONS] -- COMMAND [ARGS...]

Arguments:
  COMMAND [ARGS...]    Backend command to spawn (e.g., python -m my_mcp_server)

Server Configuration

Flag Default Description
--host HOST 127.0.0.1 Bind address
--port PORT 8080 Bind port
--path PATH /mcp HTTP endpoint path
--max-message-size BYTES 10 MiB Reject a request whose declared Content-Length exceeds this with 413, before reading any of the body; 0 disables the cap (#416)
--allow-origin ORIGIN — Also accept browser requests from this origin: scheme://host[:port], or an extension/webview origin such as chrome-extension://<id> (repeatable, exact match). Loopback origins (localhost, *.localhost, 127.0.0.0/8, [::1], any port) and the --public-url origin are always accepted (an internationalized --public-url host is not converted: list its punycode origin here); any other Origin gets 403, and requests without an Origin header (non-browser clients) are unaffected — DNS-rebinding protection (#449). It does not enable CORS: a cross-origin browser client still needs a proxy that adds CORS headers

Authentication

Flag Environment Variable Description
--auth-token TOKEN MCP_STDIO_SERVE_TOKEN Static bearer token (acts as OAuth Resource Server; optional)
--enable-oauth — Enable embedded OAuth 2.1 Authorization Server (PKCE auth-code, DCR, refresh)
--public-url URL — Public HTTPS URL pinning the issuer and well-known documents (strongly recommended behind a reverse proxy; serve still starts without it)
--trusted-user-header HEADER — HTTP header name containing the authenticated user (trusted only because the fronting proxy strips client-supplied copies)
--dev-user USER — Insecure, testing only. Stand-in user identity for loopback testing without real SSO
--access-token-ttl SECONDS 3600 Access token lifetime in seconds
--allow-redirect-uri URL — Additional redirect URI to trust for Dynamic Client Registration (repeatable; e.g., https://claude.ai/api/mcp/auth_callback for web-based clients)
--allow-client-id-url URL — Accept this exact Client ID Metadata Document URL as a client_id (repeatable; e.g., https://claude.ai/oauth/mcp-oauth-client-metadata for claude.ai). The document is fetched at /authorize and its redirect_uris become the registration. client_id_metadata_document_supported is not advertised, so other clients keep using DCR (#463)
--token-store PATH — Path to persist issued tokens, registrations, and replay tombstones. Survives restarts so clients retain valid tokens. Each serve process must have its own path. File is created 0600; treat like a private key

Session Management

Flag Default Description
--max-sessions N 100 Maximum concurrent sessions; an initialize past the cap gets 503
--session-idle-ttl SECONDS 0 (disabled) Idle timeout for OLDER clients' sessions (newer clients have --modern-idle-ttl); evict a session and its child after this much inactivity so a client that disconnects without DELETE does not pin a slot
--max-sessions-per-owner N 0 (disabled) On a new initialize, LRU-evict that OAuth user's older sessions down to N, reclaiming ghosts left by a client that reconnects without DELETE; static-token and open-gateway sessions are exempt
--drop-client-capability CAP — Remove roots, elicitation or sampling from an older client's initialize before it reaches the backend, so the backend never asks the client for it (repeatable). For clients that declare a capability but never answer it: claude.ai declares roots, and a backend that then sends roots/list times out and the connector fails to connect (anthropics/claude-ai-mcp#708, #466). Newer clients are unaffected

Newer MCP clients (2026-07-28)

Nothing to turn on — serve answers newer and older clients on the same address automatically. These flags tune caching, tidy up idle backends, and (if you want) drop older clients entirely.

Flag Default Description
--cache-ttl-ms MS 60000 How long (in milliseconds) a newer client may cache list-style results such as tools/list. 0 tells clients not to cache at all. Results are always marked private, never shared between users. Tool call results are never cached
--modern-idle-ttl SECONDS 0 (off) Shut down a backend serving newer clients after this long with no request, freeing the process. Safe to set aggressively — those clients keep no state, so they just get a fresh backend next time. A backend that is mid-request is never shut down. Separate from --session-idle-ttl, which governs older clients
--modern-only off Serve only newer clients. Older ones are turned away instead of being given a session: GET and DELETE answer 405, and an older client's initialize gets an error naming the version this endpoint does serve. OAuth discovery endpoints keep working, so login still bootstraps
--accept-claimless-resource-read off Serve a resources/read that carries no protocol claim and no session (no _meta protocol version, no MCP-Protocol-Version, no Mcp-Session-Id) as a newer-client request instead of answering 400. The Claude iOS app reads MCP App (ui://) resources that way while the rest of its conversation is a newer client (anthropics/claude-ai-mcp#1042, #469). Works with --modern-only

Newer clients can also open a long-lived connection to hear when your server's tool, prompt or resource lists change, or when a specific resource they named is updated — see Telling clients your lists changed. There is no flag for either. A client may hold up to four such connections per backend — with --enable-oauth, that means per authenticated user. Without auth, or with a shared --auth-token, every client shares one backend, so the four connections are a gateway-wide total: a fifth connection from any client is refused rather than queued. Each connection may watch up to 256 individual resource URIs; beyond that the extras are dropped and the client is told which ones it actually got. Each one sends a comment every 15 seconds so proxies do not time it out, and a backend with a connection attached is never reclaimed by --modern-idle-ttl.

Note that --modern-idle-ttl counts from the last request, and a long-lived connection is one request that never finishes — so a user who keeps one open keeps their backend alive, which is the intent.


Standards Conformance

mcp-stdio implements the following specifications:

MCP (Model Context Protocol)

  • Streamable HTTP transport (current, spec rev 2025-06-18) — negotiated MCP-Protocol-Version is captured from initialize and sent on every subsequent request
  • Streamable HTTP transport, spec rev 2026-07-28 — capability discovery, per-request metadata and headers (including Mcp-Param-* from x-mcp-header), session-less requests, cache hints on list results, the long-lived notification connection (both as a client and, in serve, for the listChanged trio and per-URI resource subscriptions), and mid-call requests back to the client. Opt in with --protocol-era; serve answers both revisions on one endpoint. Interoperability verified against python-sdk v2.0.0 in both directions
  • SSE transport (legacy, MCP 2024-11-05)
  • Client ID Metadata Documents (MCP 2025-11-25 draft extension) — see the OAuth section below

OAuth 2.1 & OpenID Connect

  • 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)
  • §3.3 resource field validation
  • §5.1 WWW-Authenticate: Bearer resource_metadata= hint

  • RFC 8414 Authorization Server Metadata

  • §3.1 well-known URL construction, including path insertion for issuers with path components
  • §3.3 issuer validation (cross-origin guard, same-origin mismatch warnings)
  • §3 OpenID Connect Discovery 1.0 fallback

  • 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 86-char code_verifier

  • RFC 8628 Device Authorization Grant

  • §3.1 device authorization request with resource indicator
  • §3.4–3.5 token polling with authorization_pending, slow_down, expired_token, and access_denied handling

  • RFC 7591 Dynamic Client Registration

  • §3 client registration request; token_endpoint_auth_method chosen from AS metadata
  • §3.2.1 client_secret_expires_at handling (auto re-register on expiry)
  • application_type: "native" per RFC 8252 §8.4

  • 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 as client_id
  • serve's embedded AS accepts allowlisted document URLs (--allow-client-id-url): exact client_id match, https or loopback redirect_uris, no shared secrets, public-address-only fetch without redirects, 5 KB cap, Cache-Control max-age (draft-02)

  • RFC 6749 OAuth 2.0

  • §2.3.1 client_secret_basic (Authorization header with percent-encoded credentials)

  • RFC 6750 Bearer Token Usage

  • §2.1 Authorization: Bearer request header

HTTP & Resilience

  • RFC 9110 HTTP Semantics
  • §10.2.3 Retry-After header parsing (delta-seconds and HTTP-date formats; formerly RFC 7231 §7.1.3)

  • HTTP 429 (Too Many Requests) and 503 (Service Unavailable) — honors Retry-After up to 60 seconds

  • Automatic retry with exponential backoff on connection errors (up to 3 retries); after a transport error that may follow delivery (read timeout, dropped response), only known replay-safe methods (read-only or idempotent) are retried — a tools/call gets an error saying it may have executed

WHATWG Server-Sent Events


Known Limitations

See WORKAROUNDS.md for known issues in:

  • Claude Code's HTTP transport
  • Claude Desktop's stdio spawn behavior (Cowork/Code sibling probe)
  • mcp-remote (TypeScript MCP client)
  • MCP SDKs (TypeScript & Python)
  • Windows stdio handling

mcp-stdio works around these issues at the wire level, or via serve as an alternative deployment, where possible.


File Locations

Component Location Permissions
OAuth token cache ~/.config/mcp-stdio/tokens.json 0600
Serve mode token store (user-specified via --token-store) 0600

Environment Variables

Variable Purpose
MCP_BEARER_TOKEN Static bearer token for client mode
MCP_OAUTH_CLIENT_ID Pre-registered OAuth client ID
MCP_OAUTH_REFRESH_LEEWAY Seconds before token expiry to trigger refresh (default: 60)
MCP_STDIO_SERVE_TOKEN Static bearer token for serve mode
MCP_STDIO_MRTR_STRIP Set to 1 to stop advertising the client's sampling / elicitation / roots capabilities to a modern-era remote, withdrawing its invitation to use the multi round-trip requests (MRTR) pattern. Escape hatch only — the relay bridges MRTR by default, and a server that sends it anyway is still bridged.
MCP_STDIO_MRTR_REVERSE_ENABLE Set to 1 to let an older serve-published server ask a newer client something mid-call — elicit input, request a sampling completion, or list roots — over MRTR, the reverse direction of MCP_STDIO_MRTR_STRIP above. Off by default; only bridges for OAuth-authenticated callers. See Answering your server's mid-call questions.
HTTPS_PROXY / HTTP_PROXY / NO_PROXY Standard proxy configuration

Exit Codes

Code Meaning
0 Success
1 Runtime error (connection failure, OAuth authentication failure, misconfiguration detected at startup)
2 Invalid command-line arguments (standard argparse usage error)
130 Interrupted (Ctrl-C / SIGINT)

Logging

  • All diagnostics are written to stderr. The relay's own connection/retry/reconnect messages are prefixed [mcp-stdio]; startup and OAuth error/warning messages print as bare error: ... / warning: ... lines instead
  • There is currently no separate verbose/debug logging mode — the stderr output above is all there is