mcp-oauth-gateway

OAuth 2.1 for MCP clients that only know how to send a static Authorization header.

Many MCP clients can't authenticate against an MCP server that implements the spec's authorization flow. They send one fixed header, never discover the authorization server, and don't react to a 401 challenge — so the server is simply unreachable:

Error POSTing to endpoint: {"error":{"code":-32001,"message":"Bearer token required"}}
Server status: needs-auth
SDK auth failed: Dynamic Client Registration rejected (HTTP 400):
  {"error":"invalid_client_metadata","error_description":"dynamic client registration is disabled..."}

Hand-pasting a long-lived JWT into the client's config "works", and then goes stale: the token expires, ends up in plaintext in several config files, and every client needs its own copy.

This gateway sits on loopback and holds the credential for the client:

        static header                    OAuth 2.1, refreshed automatically
client ───────────────▶ 127.0.0.1:33419/mcp ─────────────────────▶ your MCP server
                              │
                              └── performs RFC 9728 discovery, PKCE, and silent refresh;
                                  keeps tokens in the OS config dir (0600), not in your config

The client keeps talking to a loopback URL with a stable local token that is not the OAuth credential, so nothing in the client's config ever changes when the OAuth token rotates.

Zero dependencies. Node ≥ 20 only (it uses the built-in fetch, node:http and node:test).

What it does on the wire

1. POST <mcp-url> → reads the 401 and its WWW-Authenticate challenge.

2. Fetches the Protected Resource Metadata (RFC 9728) the challenge points at.

3. Fetches the authorization server's metadata (RFC 8414, falling back to openid-configuration).

4. Registers a client dynamically (RFC 7591) if the server allows it; otherwise it tells you exactly what to configure instead.

5. Opens the browser for an authorization code + PKCE (S256) flow, with resource=<mcp-url> (RFC 8707) so the token's audience is bound to your server.

6. Stores the access and refresh token, and renews silently before expiry.

Nothing is vendor-specific: any MCP server that publishes protected-resource metadata and any OAuth 2.1 authorization server with PKCE works.

Related MCP server: Uno MCP Stdio

Quick start

No clone needed — it is published on npm:

# 1. Authorize once (opens a browser; stores tokens outside any repo)
npx mcp-oauth-gateway login --url https://your-mcp-host/mcp

# 2. Run the gateway
npx mcp-oauth-gateway serve --url https://your-mcp-host/mcp --port 33419

# 3. Print ready-to-paste client configuration
npx mcp-oauth-gateway print-config --url https://your-mcp-host/mcp

Or from a checkout (git clone https://github.com/zmhhaha/mcp-oauth-gateway), replacing npx mcp-oauth-gateway with node bin/mcp-oauth-gateway.mjs.

If your authorization server does not offer dynamic client registration, add --client-id <id> to login. The error message tells you the redirect URI to register.

Confidential clients and server-specific parameters

The default flow is a public client: PKCE, no secret. That is the right shape for a loopback CLI and what most MCP servers accept. If your authorization server issues a client secret, pass it by environment variable so it stays out of ps and your shell history:

export MCP_CLIENT_SECRET=…          # from your secret store
npx mcp-oauth-gateway login --url https://your-mcp-host/mcp \
  --client-id <id> --client-secret-env MCP_CLIENT_SECRET

The secret is stored beside the tokens (mode 600, outside any repo) and a plain serve picks it up from there, so no flags have to be repeated. --token-auth-method client_secret_post switches away from HTTP Basic for servers that want the secret in the body. A secret handed out by dynamic registration is stored the same way.

Some servers require parameters the MCP authorization specification never mentions. Both flags repeat, and both are remembered for later refreshes:

# Google: without access_type=offline the server issues no refresh token at all
--authorize-param access_type=offline --authorize-param prompt=consent
# Auth0: the API identifier the access token must be addressed to
--token-param audience=https://api.example

Headless hosts: containers, CI, servers

The flow above opens a browser and receives the redirect on http://localhost:<port>/oauth/callback, which cannot work on a host with no browser. Use the RFC 8628 device flow instead — no browser, no listener, no port forwarding, nothing outside the process is needed to complete it:

npx mcp-oauth-gateway login --device --url https://your-mcp-host/mcp --client-id <id>

It prints a short code and a URL. Open that URL on any device where you are already signed in to the authorization server — a phone is fine — and enter the code. The command polls until you approve, then stores exactly what the browser flow would have stored (refresh token included), so later restarts renew silently.

The authorization server must advertise device_authorization_endpoint and must have the device flow enabled for your client. For Casdoor that means the application needs both the Device Code grant type and a Device login signin method; 4.11.0's UI can set only the first, so see Casdoor notes.

Pointing a client at it

DSH (DeepSeek Harness)

DSH's MCP client has no OAuth at all, so this is the intended use case.

This repository is the DSH bundle — its package.json declares dsh.bundle.patch — so the Plugins panel can install it straight from this repository's URL or from a local checkout. (DSH has no browsable marketplace: it installs from a package name on npm, a Git repository URL, a tarball, or a local path, and otherwise only lists DSH's own official plugins. This package is published on npm, so the package-name route works too.)

See dsh/README.md for the two values print-config gives you, and the caveats.

Any client that accepts custom headers

{
  "mcpServers": {
    "your-server": {
      "type": "http",
      "url": "http://127.0.0.1:33419/mcp",
      "headers": { "x-mcp-gateway-token": "<from print-config>" }
    }
  }
}

Good old curl

curl -sS -X POST http://127.0.0.1:33419/mcp \
  -H "x-mcp-gateway-token: <from print-config>" \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

Clients that do implement OAuth (Claude Code, Codex with its experimental Rust client) should keep using their own flow — this gateway is for the ones that can't.

Commands

Security and limitations

• Loopback only. It binds 127.0.0.1 and ::1 (both, because localhost resolves to either — a mismatch here breaks the browser redirect). It refuses any request without its token.

• The local token is not the OAuth credential. It is stable and can live in client config files; the OAuth tokens stay in the gateway's state file (mode 0600 under the OS config dir, never in a client's config).

• Same-user processes can read that state file. The gateway's token is readable by anything running as you — the same trust boundary as any local dev tool. Do not run it on a shared machine as a shared user.

• One upstream per process, one login at a time, in-memory state. Run several gateways (one port each) for several MCP servers.

• Keep it running. Tokens refresh only while the gateway runs. A refresh token has its own lifetime on the authorization server, so a gateway that stays down past it needs a fresh login — starting it on demand works, but leaving it running is what makes the setup hands-off.

• No retry on a mid-flight 401. Expiry is handled proactively (including reading exp from the JWT when the server omits expires_in); a token that the server rejects anyway means re-login.

• chmod 0600 is POSIX-only. On Windows the ACL of your own profile directory is the boundary.

• The gateway does not verify tokens or signatures — that is the MCP server's job. It only obtains and forwards them.

Troubleshooting

Development

node --test          # 32 tests, no network required

The suite covers the RFC 7636 PKCE vector, challenge and metadata parsing, the manual-client error paths, token-store semantics, the loopback proxy (including a test that proves SSE frames are streamed and not buffered), and the transport selection per upstream scheme.

Releasing

Two traps that cost real time on the first publish, both silent:

1. Never write a bin path with a leading ./. "mcp-oauth-gateway": "./bin/x.mjs" makes npm consider the entry invalid and drop the whole bin field from the published package — npm publish only warns, and npx then fails with no obvious cause. Use "bin/x.mjs". npm pkg fix corrects it.

2. npm 11 has staged publishing, and a bypass-2FA token is no longer the recommended route. npm publish may leave the version unpublished while the registry reserves the name with a 0.0.0-stage placeholder; the metadata for a brand-new package also takes a minute to appear, so an immediate npm view or npx <pkg>@<version> can report ETARGET even though the publish succeeded. Check the version endpoint (registry.npmjs.org/<pkg>/<version>) before concluding anything, and prefer npm stage publish + npm stage approve over a bypass token (npm's own guidance). npm stage list reads GET /-/stage.

Notes on specific authorization servers

• Casdoor — DCR behaviour, aud = resource, redirect matching, and the configuration cache that quietly reverts database edits.

License

MIT