mcp-stdio

English | 日本語

Stdio-to-HTTP gateway — connects MCP clients to remote HTTP MCP servers.

📖 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

MCP clients like Claude Desktop and Claude Code 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[Claude<br>Desktop/Code] <-- 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.

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