mcp-oauth-test-server

mcp-oauth-test-server

A small, configurable OAuth 2.0 authorization server + OAuth-protected MCP server for testingOAuth-protected MCP flows end to end — discovery, interactive consent (PKCE), token refresh,refresh-token rotation, access-token expiry, revocation, and deliberate error injection.

It exists so you can exercise an OAuth-MCP client or integration against a provider you fully control— including the failure modes a real provider won't let you trigger on demand (rotate the refreshtoken, expire/revoke the access token, force invalid_grant, deny consent, return 403 insufficient_scope).

⚠️ Test only. It auto-approves every consent request, keeps all state in memory, and performs noreal authentication. Never expose it as a real authorization server.

What's in the box

Two HTTP servers, started together by npm start:

The MCP server validates bearer tokens by calling the OAuth server's /introspect, so the two talkover HTTP and can run on different hosts.

Run

npm install
npm start
# [oauth] authorization server  http://localhost:9100  (http)
# [mcp]   protected MCP server   http://localhost:9101/mcp

HTTPS (for clients that connect directly)

The servers default to plain HTTP. A client that connects to the sim directly over HTTPS needs acert. (A client that can't reach loopback — e.g. one behind an SSRF-guarded proxy — needs a publictunnel instead; see Using it behind a public tunnel. With a tunnelthe sim can stay HTTP.)

npm run certs   # generates a self-signed cert in ./certs (gitignored)
npm start       # auto-detects the cert and serves HTTPS; base URLs switch to https://

The cert is self-signed, so the connecting client must trust it — macOS keychain:sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ./certs/localhost.pem;Node clients: NODE_EXTRA_CA_CERTS=…/certs/localhost.pem (or NODE_TLS_REJECT_UNAUTHORIZED=0).

Configure via env (see .env.example): OAUTH_PORT, MCP_PORT, OAUTH_BASE_URL, MCP_BASE_URL,TLS_CERT_FILE, TLS_KEY_FILE, SEED_REFRESH_TOKEN, TOKEN_TTL_SECONDS, SCOPES.

*_BASE_URL are the URLs embedded in the discovery documents — they must be reachable by whoever doesdiscovery + token exchange. For direct local use that's localhost; behind a tunnel, set them to thepublic URLs (see below).

The discovery chain

A compliant MCP/OAuth client can bootstrap from just the MCP server URL:

1. Client hits POST /mcp with no token → 401 + WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource".
2. Client fetches /.well-known/oauth-protected-resource (RFC 9728) → authorization_servers: ["http://localhost:9100"].
3. Client fetches http://localhost:9100/.well-known/oauth-authorization-server (RFC 8414) → authorization_endpoint, token_endpoint, registration_endpoint, …
4. Client (optionally) registers via /register (RFC 7591), then runs the authorization-code + PKCE flow.

Endpoints

OAuth server (:9100)

• GET /.well-known/oauth-authorization-server — RFC 8414 metadata
• GET /authorize — authorization-code flow, auto-approves, validates/echoes PKCE code_challenge (S256)
• POST /token — authorization_code (PKCE-verified) and refresh_token grants
• GET /introspect?token=… — { active, scope }
• POST /register — dynamic client registration (RFC 7591)

MCP server (:9101)

• GET /.well-known/oauth-protected-resource — RFC 9728 metadata
• POST /mcp — Streamable-HTTP MCP; bearer-validated. Tools: echo, add, whoami
• GET /mcp — 405 (stateless server)

Control plane (inject failures)

# OAuth server
curl -XPOST localhost:9100/control/rotate         -d '{"on":true}'  -H content-type:application/json   # rotate refresh token each refresh
curl -XPOST localhost:9100/control/expires-in     -d '{"seconds":5}' -H content-type:application/json   # short access-token TTL
curl -XPOST localhost:9100/control/revoke-access                                                        # invalidate all access tokens (→ MCP 401)
curl -XPOST localhost:9100/control/invalid-grant  -d '{"on":true}'  -H content-type:application/json    # refresh-grant → invalid_grant
curl -XPOST localhost:9100/control/deny-consent   -d '{"on":true}'  -H content-type:application/json    # /authorize → access_denied
curl -XPOST localhost:9100/control/seed-refresh   -d '{"token":"…"}' -H content-type:application/json    # mark a refresh token valid
curl -XPOST localhost:9100/control/reset                                                                # clear all state
curl       localhost:9100/control/state

# MCP server
curl -XPOST localhost:9101/control/force-403      -d '{"on":true}'  -H content-type:application/json    # tool access → 403 insufficient_scope
curl -XPOST localhost:9101/control/reset

Scenarios these unlock

Driving a scenario (npm run scenario)

scripts/scenario.sh flips the control plane by name, so you don't have to remember the raw curls(it talks to the local control ports — HTTPS when ./certs exists, else HTTP):

npm run scenario -- state             # show control-plane state (token counts, refresh tokens)
npm run scenario -- rotate on         # refresh-token rotation on every refresh-grant
npm run scenario -- expire-access 5   # hand clients a 5s access-token TTL
npm run scenario -- revoke            # revoke live access tokens (next call → upstream 401)
npm run scenario -- dead-refresh on   # refresh grant → invalid_grant
npm run scenario -- deny-consent on   # /authorize → access_denied
npm run scenario -- bad-scope on      # tool calls → 403 insufficient_scope
npm run scenario -- reset             # ⚠ wipes state — invalidates deposited creds (re-consent)
# direct: ./scripts/scenario.sh <scenario> [on|off|secs]

Loop: set a scenario → trigger a tool call from your client (run the action that uses a tool, orrefresh the client's tool list) → watch the sim console + scenario state to confirm:

Using it behind a public tunnel

Some OAuth-MCP clients enforce SSRF protection: they require HTTPS and block localhost,loopback, and private IPs. To drive consent from one, the sim must be reachable at a public HTTPSURL — a tunnel is the simplest way, and it terminates TLS for you (the sim itself can stay on plainHTTP, no local cert needed).

1. Expose both servers with cloudflared

cloudflared "quick tunnels" need no account. The sim is two servers, so run two (each prints ahttps://<random>.trycloudflare.com URL):

brew install cloudflared   # once

cloudflared tunnel --url http://localhost:9101    # MCP   → https://<mcp-host>.trycloudflare.com
cloudflared tunnel --url http://localhost:9100    # OAuth → https://<oauth-host>.trycloudflare.com

(If you're running the sim over HTTPS instead, add --no-tls-verify to each.)

2. Point the sim's discovery at the public URLs

Discovery docs must advertise the public URLs, so restart the sim with them as base URLs:

MCP_BASE_URL=https://<mcp-host>.trycloudflare.com \
OAUTH_BASE_URL=https://<oauth-host>.trycloudflare.com \
npm start

⚠ Quick-tunnel URLs are ephemeral — restart the sim whenever they change. Every cloudflared(re)start mints a new random URL. OAUTH_BASE_URL is used not just for discovery but for the MCPserver's token introspection (it calls OAUTH_BASE_URL/introspect), so if you rebuild thetunnels and don't restart the sim with the new URLs, refresh still succeeds but the MCP call failswith 401 (introspection failed) fetch failed — the sim is introspecting against the dead old URL.Repointing only the client's stored endpoints is not enough. And because restarting the simresets its in-memory token state (validRefresh), any previously-issued refresh token isinvalidated → the client must re-consent.

3. Point your client at it

Give your OAuth-MCP client the public MCP URL (https://<mcp-host>.trycloudflare.com/mcp) withOAuth 2.0 auth. The client auto-discovers the authorization server (no need to hand-enter theauthorize/token URLs), and since the sim supports dynamic client registration it obtains clientcredentials automatically. Then toggle the control plane to exercise the refresh / rotation / revoke/ re-auth paths.

Quick-tunnel URLs are ephemeral — redo steps 2–3 if you restart the tunnels. Alocalhost/loopback URL will fail any client that enforces an SSRF/HTTPS check (typically a422 "URL must use HTTPS" or a blocked-host error).

License

Set your organization's standard license before publishing (currently UNLICENSED).