# mcp-stdio English | [日本語](README.ja.md) Stdio-to-HTTP gateway — connects MCP clients to remote HTTP MCP servers. 📖 **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 [MCP](https://modelcontextprotocol.io/) 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: ```mermaid flowchart BT A[Claude
Desktop/Code] <-- 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. ## 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](https://html.spec.whatwg.org/multipage/server-sent-events.html). - **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](https://www.rfc-editor.org/rfc/rfc9728) 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](https://www.rfc-editor.org/rfc/rfc8414) 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](https://www.rfc-editor.org/rfc/rfc8707) Resource Indicators - §2 `resource` parameter in authorization, token exchange, **and refresh** requests - [RFC 7636](https://www.rfc-editor.org/rfc/rfc7636) PKCE - §4.1–4.2 S256 `code_challenge_method` with an 86-char `code_verifier` - [RFC 8628](https://www.rfc-editor.org/rfc/rfc8628) 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](https://www.rfc-editor.org/rfc/rfc7591) 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](https://www.rfc-editor.org/rfc/rfc8252) §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

Command Palette

Tagged “bearer-tokens”

Servers

mcp-stdio