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 — 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<br>Claude / Codex / …] <-- stdio --> B(mcp-stdio)
    B <== "<b>HTTPS</b><br>Streamable HTTP / SSE<br>Bearer Token<br>Header<br>OAuth" ==> C[Remote<br>MCP Server]
    B -. "OAuth 2.1<br>(PKCE)" .-> D[Authorization<br>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

Install

pip install mcp-stdio

Or with uv:

uv tool install mcp-stdio

Or run directly without installing:

uvx mcp-stdio https://your-server.example.com:8080/mcp

Or with Homebrew:

brew install shigechika/tap/mcp-stdio

Quick Start

mcp-stdio https://your-server.example.com:8080/mcp

With Bearer token authentication:

# Recommended: use env var (token is hidden from `ps`)
MCP_BEARER_TOKEN=YOUR_TOKEN mcp-stdio https://your-server.example.com:8080/mcp

# Or pass directly (token is visible in `ps` output)
mcp-stdio https://your-server.example.com:8080/mcp --bearer-token YOUR_TOKEN

With custom headers:

mcp-stdio https://your-server.example.com:8080/mcp --header "X-API-Key: YOUR_KEY"

With OAuth 2.1 authentication (for servers that require it):

mcp-stdio --oauth https://your-server.example.com:8080/mcp

# With a pre-registered client ID (skips dynamic registration)
mcp-stdio --oauth --client-id YOUR_CLIENT_ID https://your-server.example.com:8080/mcp

With OAuth 2.1 Device Authorization Grant (RFC 8628, for headless/SSH environments):

mcp-stdio --oauth-device https://your-server.example.com:8080/mcp

For legacy MCP servers using the 2024-11-05 SSE transport:

mcp-stdio --transport sse https://your-server.example.com:8080/sse

Check connectivity before use:

mcp-stdio --check https://your-server.example.com:8080/mcp

# For an SSE server, pass --transport sse so --check runs the legacy
# GET/endpoint/POST handshake instead of a Streamable HTTP probe:
mcp-stdio --check --transport sse https://your-server.example.com:8080/sse

Claude Desktop Configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "my-remote-server": {
      "command": "mcp-stdio",
      "args": ["https://your-server.example.com:8080/mcp"],
      "env": {
        "MCP_BEARER_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Claude Code Configuration

claude mcp add my-remote-server \
  -e MCP_BEARER_TOKEN=YOUR_TOKEN \
  -- mcp-stdio https://your-server.example.com:8080/mcp

Codex Configuration

codex mcp add my-remote-server \
  --env MCP_BEARER_TOKEN=YOUR_TOKEN \
  -- mcp-stdio https://your-server.example.com:8080/mcp

The same pattern works for any MCP client that launches stdio servers: give it mcp-stdio as the command and the remote URL (plus any options) as arguments.

Usage

mcp-stdio [OPTIONS] URL

Arguments:
  URL                    Remote MCP server URL

Options:
  --bearer-token TOKEN   Bearer token (or set MCP_BEARER_TOKEN env var)
  --oauth                Enable OAuth 2.1 authentication (browser flow)
  --oauth-device         Enable OAuth 2.1 Device Authorization Grant (RFC 8628, headless)
  --client-id ID         Pre-registered OAuth client ID (or set MCP_OAUTH_CLIENT_ID)
  --client-metadata-url URL
                         HTTPS URL of a Client ID Metadata Document you host
                         (draft-ietf-oauth-client-id-metadata-document-00), used
                         as client_id instead of Dynamic Client Registration.
                         Ignored if --client-id is also given (#60)
  --oauth-scope SCOPE    OAuth scope to request
  --oauth-use-id-token   Present the OIDC id_token as the Bearer credential
                         instead of the access_token (AWS Bedrock AgentCore /
                         Cognito); falls back to access_token if none is returned (#59)
  --oauth-eager          Cold-start: answer initialize locally and run the
                         interactive OAuth flow in the background, so a long
                         browser/SSO/MFA login does not blow the client's ~60 s
                         initialize timeout. Streamable HTTP only; ignored on
                         --transport sse. Warm cache unaffected (#296)
  --oauth-refresh-leeway SECONDS
                         Proactively refresh tokens this many seconds before
                         expiry (default: 60, or MCP_OAUTH_REFRESH_LEEWAY)
  --no-proactive-refresh
                         Disable the background timer that refreshes the OAuth
                         token before it expires. On by default in OAuth mode;
                         keeps long sessions alive against gateways that signal
                         expiry as an HTTP 200 tool-error rather than a 401 (#242)
  --no-oauth-reauth      Do not sign in again in the background when the refresh
                         token stops working mid-session (on by default; #471)
  --oauth-timeout SECONDS
                         Seconds to wait for the interactive OAuth flow (browser
                         callback / device-code confirmation) before giving up
                         (default: 120; OAuth only)
  --no-resource-indicator
                         Omit the RFC 8707 resource parameter from all OAuth
                         requests. Required for AS that reject it, such as
                         Microsoft Entra ID v2 with api:// scopes (AADSTS9010010).
                         Persisted in the token store so proactive refreshes
                         and step-up flows stay consistent
  --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.
                         Microsoft Entra ID's App ID URI api://<app-id>. Persisted
                         in the token store. Mutually exclusive with
                         --no-resource-indicator
  -H, --header 'Key: Value'  Custom header (can be repeated)
  --transport {streamable-http,sse}
                         Transport type (default: streamable-http)
  --timeout-connect SEC  Connection timeout (default: 10)
  --timeout-read SEC     Read timeout (default: 120)
  --sse-read-timeout SEC Idle read timeout on the SSE GET stream
                         (default: 300; 0 disables; SSE transport only)
  --no-tcp-keepalive     Disable TCP keepalive on the HTTP socket
  --max-message-size BYTES
                         Cap on a single upstream response body (JSON or
                         cumulative SSE stream) buffered before parsing
                         (default: 10 MiB; 0 disables the cap; #416).
                         Sends Accept-Encoding: identity by default (#417);
                         -H 'Accept-Encoding: gzip'/deflate opts back in
                         with a genuinely size-bounded decoder (#418) —
                         anything else needs --max-message-size 0.
                         Also covers this relay's own OAuth traffic (#419)
  --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
  --check                Check connection and exit
  -V, --version          Show version
  -h, --help             Show help

Run mcp-stdio --help for the full per-flag detail (platform notes and issue references are more verbose than this table).

Reverse gateway: serve mode

The default mode bridges stdio → HTTP (client side). The serve subcommand is the mirror image — HTTP → stdio — exposing a local stdio MCP server as a Streamable HTTP MCP endpoint so clients that cannot spawn it locally can reach it over the network:

flowchart BT
    A["MCP client<br>Claude / claude.ai / Codex /<br>Meta Muse<br>(or mcp-stdio --oauth)"]
    B("mcp-stdio serve<br><b>HTTP → stdio</b> gateway<br>auth: none / static token /<br>embedded OAuth 2.1 AS")
    C["local stdio<br>MCP server"]
    A <== "Streamable HTTP<br>Bearer / OAuth 2.1 (PKCE)" ==> B
    B <-- "stdio (spawned child)" --> C

This is the mirror of the client-side diagram at the top: there mcp-stdio is stdio → HTTP; here it is HTTP → stdio.

mcp-stdio serve --port 8080 -- python -m my_mcp_server

Then point any MCP client (including mcp-stdio itself) at it:

mcp-stdio --check http://127.0.0.1:8080/mcp

• Stdlib only (http.server) — adds no runtime dependency.
• Implements the Streamable HTTP request/response and notification semantics, session management, plus a GET SSE channel for server-initiated messages.
• Authentication is optional and layered:
  • No token — the endpoint is open (run it behind a TLS-terminating proxy).
  • Static token (--auth-token / MCP_STDIO_SERVE_TOKEN) — acts as an OAuth Resource Server: MCP requests require Authorization: Bearer <token>, and a 401 advertises RFC 9728 Protected Resource Metadata at /.well-known/oauth-protected-resource.
  • Embedded OAuth AS (--enable-oauth) — a minimal OAuth 2.1 Authorization Server (PKCE auth-code, RFC 7591 dynamic client registration with the invalid_redirect_uri error per §3.2.2, refresh, opaque in-memory tokens, stdlib only). An https issuer echoes the RFC 9207 iss parameter on the authorization response (mix-up defence) and advertises it in metadata. The mcp-stdio client's --oauth flow then works against the gateway.
• Embedded-AS token security: the Resource Server validates token audience (RFC 8707 / MCP — a token issued for another resource is rejected); a presented-but-invalid token gets error="invalid_token" (RFC 6750 §3.1); and replaying an authorization code or a rotated refresh token revokes the whole grant family (RFC 6749 §4.1.2 / RFC 9700 §4.14.2), with a brief grace window so a benign client retry is not punished.
• Multi-client isolation by session — each MCP session gets its own spawned backend child, so concurrent clients are isolated by process boundary (a JSON-RPC id collision across clients can never cross responses). Per the MCP Streamable HTTP spec, mints an , every later request carries it, an unknown/terminated id gets (the client then re-initializes), and a tears that session's child down. A concurrent-session cap guards an open gateway against unbounded child spawns. When OAuth is enabled each session is — a session id presented with a different user's token is rejected (), so a leaked id cannot cross tenants.

Static-token example (token via env so it is not visible in ps):

MCP_STDIO_SERVE_TOKEN=your-secret mcp-stdio serve --port 8080 -- python -m my_mcp_server
mcp-stdio --bearer-token your-secret --check http://127.0.0.1:8080/mcp

Embedded-OAuth example. User authentication is delegated to a fronting reverse proxy that asserts the logged-in user via a header (--trusted-user-header, only trusted behind a proxy that strips client copies). --dev-user is an insecure loopback-only shortcut for local testing:

mcp-stdio serve --enable-oauth --public-url http://127.0.0.1:8080 \
  --dev-user alice --port 8080 -- python -m my_mcp_server
mcp-stdio --oauth http://127.0.0.1:8080/mcp

Options: --host (default 127.0.0.1), --port (default 8080), --path (default /mcp), --auth-token TOKEN (or MCP_STDIO_SERVE_TOKEN, preferred); session limits --max-sessions N (default 100; an initialize past the cap gets 503), --session-idle-ttl SECONDS (evict a session and its child after this much inactivity so a client that disconnects without DELETE does not pin a slot; 0 = disabled, the default), and --max-sessions-per-owner N (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; 0 = disabled, the default; static-token and open-gateway sessions are exempt); --max-message-size BYTES (reject a request whose declared Content-Length exceeds this with 413, before reading any of the body; default 10 MiB, 0 disables the cap; #416); --user-env VAR (inject the authenticated principal into each spawned child's environment under this name, so a multi-user-aware backend can read its caller's identity without its own OAuth stack — requires --enable-oauth; the open-gateway and shared static-token principals are exempt, same as --max-sessions-per-owner; refuses a search-path / dynamic-linker variable name such as PATH, LD_PRELOAD, or PYTHONPATH that the child's own runtime needs to start); --drop-client-capability CAP (repeatable; roots, elicitation or sampling: removed from a legacy client's initialize before the backend sees it, for clients that declare a capability but never answer it — claude.ai declares roots, and a backend that then sends roots/list times out, anthropics/claude-ai-mcp#708, #466); --accept-claimless-resource-read (serve a sessionless resources/read that carries no protocol claim as a 2026-07-28 request instead of a 400 — the Claude iOS app reads MCP App ui:// resources that way, anthropics/claude-ai-mcp#1042, #469); --allow-origin ORIGIN (repeatable; a browser request whose Origin is not loopback, the --public-url origin, or one of these gets 403, which closes the DNS rebinding path to a loopback gateway; requests without an header, as non-browser MCP clients send them, are unaffected; it adds no CORS headers; #449); and for the embedded AS: , (pins the issuer; recommended behind a proxy), , (insecure, testing only), , (repeatable; see below), (repeatable; see below), or (mutually exclusive, see below). Without either, tokens are in-memory only and a restart invalidates them (the client re-runs ). The backend command follows the options (an optional separator is supported).

• Non-loopback remote clients — DCR only accepts an RFC 8252 loopback http:// redirect_uri by default, which a browser-based remote MCP client (a web app with a fixed HTTPS OAuth callback, not a locally-run CLI/native app) cannot satisfy. --allow-redirect-uri URL (repeatable) trusts one additional redirect_uri byte-for-byte — no host, prefix, or port matching — so add only a URL you have verified belongs to a client you actually trust; each entry is exactly as trusted as a hardcoded redirect target. It is independent of the loopback path (adding one never widens the other) and requires --enable-oauth. Examples: https://claude.ai/api/mcp/auth_callback (claude.ai), https://agent.meta.ai/api/hatch/oauth/callback (Meta Muse).
• Client ID Metadata Documents — --allow-client-id-url URL (repeatable) accepts that exact HTTPS URL as a client_id (draft-ietf-oauth-client-id-metadata-document, which MCP 2026-07-28 prefers over DCR): serve fetches the document at /authorize and uses its redirect_uris as the registration, so --allow-redirect-uri is not needed for that client. claude.ai's "No sign-in" connectors need --allow-client-id-url https://claude.ai/oauth/mcp-oauth-client-metadata. Only allowlisted URLs are fetched, only from public addresses, without redirects; requires --enable-oauth (#463).
• Restart-durable tokens — --token-store PATH persists the issued tokens, rotation tombstones, and client registrations to a JSON file (created 0600, written atomically on every state change), so a client that held a valid token before a restart keeps calling tools without a new interactive authorization, and a refresh presented after the restart is honored. This keeps deploys transparent for remote clients that do not re-authorize on 401/invalid_grant (they would otherwise replay the dead token indefinitely and appear connected while their tools silently vanish). Refresh-token reuse detection and grant-family revocation survive the restart too — the consumption ledger is part of the persisted state. The file is credential material: guard it like a private key, and give each serve process its own path — a sidecar .lock file refuses a second process at startup (sharing one store would silently clobber issued tokens), and the path is probe-written at launch so a misconfigured target fails the start instead of silently disabling persistence. Requires --enable-oauth (#277).
• Restart-durable tokens, no local disk — --token-store-firestore COLLECTION/DOCUMENT persists the same state as (same JSON-shaped snapshot, same probe-write-at-launch fail-fast behavior) to one document instead of a local file, for a deployment with no durable local disk (Cloud Run and similar). The GCP project is resolved the standard google-cloud way ( env var, or ADC on Cloud Run) — there is no separate flag. Requires the package (, an optional extra — plain never needs it) and . , but each write goes through a read-merge-write transaction rather than a blind overwrite (#406), so a brief overlap between two writers (e.g. a Cloud Run revision cutover) does not silently discard tokens either side issued or rotated during the overlap. One residual gap remains: a token revoked (replay detected) or evicted for capacity during that same overlap window can still be resurrected by a concurrently-stale writer, since those removals carry no tombstone (#428). Mutually exclusive with .

Multi-user deployment

serve is built for multiple concurrent users. Each MCP session gets its own spawned backend child and — with OAuth enabled — is bound to the authenticated user, so users are isolated by process boundary and a leaked session id cannot cross tenants.

End-user login is delegated to a fronting reverse proxy that performs the real SSO and asserts the user via --trusted-user-header (trusted ONLY because the proxy strips any client-supplied copy). The embedded AS then mints per-user tokens, and the gateway binds each session to that user.

flowchart TD
    UA["User A<br>mcp-stdio --oauth"]
    UB["User B<br>mcp-stdio --oauth"]
    RP["Reverse proxy<br>SSO login, sets X-Forwarded-User<br>strips any client-supplied copy"]
    GW["mcp-stdio serve --enable-oauth<br>--trusted-user-header X-Forwarded-User"]
    CA["stdio child<br>session of A"]
    CB["stdio child<br>session of B"]
    UA == "Streamable HTTP<br>OAuth 2.1 (PKCE)" ==> RP
    UB == "Streamable HTTP<br>OAuth 2.1 (PKCE)" ==> RP
    RP ==> GW
    GW -- "spawn per session" --> CA
    GW -- "spawn per session" --> CB

Gateway (bound to loopback, behind the proxy):

mcp-stdio serve --enable-oauth \
  --public-url https://mcp.example.org \
  --trusted-user-header X-Forwarded-User \
  --max-sessions 200 --session-idle-ttl 900 --max-sessions-per-owner 1 \
  --host 127.0.0.1 --port 8080 -- python -m my_mcp_server

• --public-url pins the issuer to the external HTTPS URL the proxy serves.
• --trusted-user-header is the header the proxy sets after login; the gateway trusts it only because the proxy strips any client-supplied copy.
• --max-sessions caps concurrent per-user children; --session-idle-ttl reclaims a child after a user disconnects without sending DELETE.
• --max-sessions-per-owner reclaims a user's previous sessions the moment they re-initialize, so a client that reconnects without DELETE (common for hosted connectors) no longer leaves ghosts. Because ghosts are reclaimed at reconnect rather than only by the idle reaper, a longer --session-idle-ttl no longer risks ghosts filling --max-sessions — which lets an interactive client with pauses avoid frequent re-initialization.

Each user points their client at the gateway, runs the OAuth flow once, and is served by a dedicated child:

mcp-stdio --oauth https://mcp.example.org/mcp

Notes:

• Isolation is by process boundary — user A and user B never share a child, so per-connection backend state (or a JSON-RPC id collision) cannot leak across them.
• The backend command is a template: every session spawns the same command as a fresh child. Identity is enforced at the gateway (session→user binding); it is not injected into the child today, so a backend that needs per-user context should derive it from the request, or run one gateway per backend configuration (optionally multiplexed by path — see Path-scoped issuer).

Workarounds

See WORKAROUNDS.md for known issues in Claude Code, Claude Desktop, mcp-remote, the MCP SDKs, and Windows that mcp-stdio addresses.

How It Works

1. If --oauth (browser) or --oauth-device (headless, RFC 8628) is set, obtains an access token (cached → refresh → browser/device flow)
2. Reads JSON-RPC messages from stdin (sent by the MCP client)
3. Relays them over HTTPS to the remote MCP server
4. Parses responses and writes them to stdout
5. On 401 (OAuth mode only), refreshes the access token and retries; when the refresh itself is rejected, it re-authorizes in the background and answers -32002 until the sign-in completes (#471); with static --bearer-token / -H auth the 401 is surfaced to the client
6. In OAuth mode a background timer also refreshes the token shortly before it expires (--oauth-refresh-leeway), independent of request flow — this keeps long sessions alive against gateways that report token expiry as an HTTP 200 tool-error rather than a 401 (opt out with --no-proactive-refresh)

Transport details:

• Streamable HTTP (default) — each stdin message is a single POST; session state is tracked via the Mcp-Session-Id header and re-initialized automatically on 404. The negotiated MCP-Protocol-Version header is sent on every post-initialize request (spec rev 2025-06-18).
• SSE (MCP 2024-11-05 legacy) — a persistent GET stream delivers responses and the initial endpoint event containing the POST URL; the stream auto-reconnects on disconnect.

OAuth tokens are stored in ~/.config/mcp-stdio/tokens.json (permissions 0600).

License

MIT