mcp-oauth-starter

A minimal remote MCP server that actually requires authorization — built against the 2026-07-28 spec revision, with OAuth 2.1 resource-server semantics wired up and tested.

Most public MCP examples run unauthenticated on stdio, which is fine on your laptop and useless the moment the server is a URL someone else's Claude connects to. This is the other half: a server that answers 401 with a discovery pointer, validates the token it gets back, and refuses tokens that were minted for somebody else.

Why this exists

The MCP authorization profile moved on 2026-07-28 (previous revision: 2025-11-25), and most tutorials still describe the older world. Three changes matter if you are writing a connector now:

Verified against mcp 2.2.0, where mcp.types.LATEST_PROTOCOL_VERSION == "2026-07-28".

Related MCP server: MCP OAuth Test

The one rule you cannot skip

MCP servers MUST validate that access tokens were issued specifically for them as the intended audience, according to RFC 8707 Section 2. — MCP 2026-07-28, Token Handling

A signed, unexpired, entirely legitimate token issued for another resource server must be rejected here. Accept it and your server becomes a replay target: anyone holding a token for any other service on the same authorization server can drive your tools. That is the confused-deputy problem, and it is one audience= argument away from being a real breach.

This repo enforces it twice — once in verifier.py via jwt.decode(..., audience=...), and again through validate_token_resource=True in the bearer middleware. There is a test for it: test_token_for_another_audience_is_rejected.

What the SDK leaves to you

mcp 2.2.0 publishes the RFC 9728 metadata document and emits a 401 with error, error_description and resource_metadata — but not the RFC 6750 scope parameter, which the spec says servers SHOULD send. Without it a client falls back to scopes_supported from the metadata document, costing an extra round trip on every cold start.

challenge.py is a small ASGI wrapper that appends it:

WWW-Authenticate: Bearer error="invalid_token", error_description="Authentication required",
                  resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/mcp",
                  scope="notes:read notes:write"

The flow

sequenceDiagram
    participant C as MCP Client
    participant M as This server<br/>(resource server)
    participant A as Authorization Server

    C->>M: POST /mcp (no token)
    M-->>C: 401 + WWW-Authenticate:<br/>Bearer resource_metadata="...", scope="notes:read"
    C->>M: GET /.well-known/oauth-protected-resource/mcp
    M-->>C: { resource, authorization_servers, scopes_supported }
    C->>A: Discover metadata, then authorize (PKCE + resource=<canonical URI>)
    A-->>C: Access token, aud = this server
    C->>M: POST /mcp + Authorization: Bearer ...
    M->>M: Verify signature, iss, aud, exp
    M-->>C: Tool result

Quickstart

git clone https://github.com/specter-systems/mcp-oauth-starter
cd mcp-oauth-starter
pip install -e ".[dev]"

cp .env.example .env      # then edit it — see the table below
set -a && source .env && set +a
mcp-oauth-starter         # serves on http://127.0.0.1:8000/mcp

Confirm the discovery document and the challenge before you connect a client:

curl -s localhost:8000/.well-known/oauth-protected-resource/mcp | jq
curl -si -X POST localhost:8000/mcp \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -12

You should get a 401 whose WWW-Authenticate header names the metadata URL. If you get a 200, your server is unprotected — stop and fix that before deploying anything.

Configuration

Scopes

MCP_REQUIRED_SCOPES gates the whole server. Individual tools can ask for more — write_note calls require_scope("notes:write") — which is what you want when one connector exposes both reads and writes and you would rather not hand every caller write access.

Per the spec, return all scopes needed for an operation in a single 403 challenge. Challenging for one missing scope at a time forces repeated authorization round-trips and makes the connector feel broken.

Tests

pytest -q

Covers audience rejection, issuer rejection, expiry, missing aud, malformed tokens, the scope / scp claim shapes that Okta and Entra disagree about, the RFC 9728 discovery document, the shape of the 401 challenge, and the scope parameter added on top of it.

What this is not

• Not an authorization server. It does not issue tokens. Point it at one you run or buy.

• Not a production connector. It is the auth scaffolding with three illustrative tools; the business logic is yours.

• Not opaque-token ready. It assumes JWTs. For opaque tokens, swap verify_token for an RFC 7662 introspection call and cache the result.

License

MIT — see LICENSE.

Built by Specter Systems — Claude MCP connectors, Python data pipelines and outreach automation. Doha, Qatar; working remotely.