MCP Auth — OAuth Gateway for Model Context Protocol Servers

What this is

MCP Auth is an OAuth authorization server + reverse proxy for Model Context Protocol servers. You register an upstream MCP server URL, set email or domain-based access rules, and get a stable authenticated endpoint that any MCP client (Cursor, Claude Desktop, etc.) can connect to using the standard MCP auth flow — no custom headers, no API keys, no workarounds.

For server owners

For MCP users

One-click install via Cursor deeplink. Authenticate once with Google, access all servers shared with you.

How the auth flow works

The flow follows the MCP authorization specification (spec § Authorization), which is built on OAuth 2.1 with PKCE, Resource Indicators (RFC 8707), and Protected Resource Metadata (RFC 9728).

Client sends a request to /mcp/{serverId} without a token. Gateway responds 401 with WWW-Authenticate: Bearer resource_metadata="...".

Client fetches /.well-known/oauth-protected-resource to discover the authorization server.

Client fetches /.well-known/oauth-authorization-server (or /.well-known/openid-configuration) for endpoint details, supported scopes, and PKCE requirements.

Client starts an authorization code flow to /authorize with PKCE S256. The gateway redirects to Google OIDC for identity verification.

After Google login, the gateway checks the ACL for the target server against the user's identity. If allowed, it issues an authorization code and redirects back to the client.

Client exchanges the code at POST /token for a JWT access token (RS256, audience-bound) and a rotating refresh token.

Client retries the original MCP request with Authorization: Bearer {token}. Gateway validates the JWT, checks ACL, proxies to the upstream server, and logs usage.

Spec compliance & quirks

Things we learned the hard way

Cursor doesn't send the resource parameter during OAuth authorization (as of 2026). The spec says clients should include it (spec § 2.4), but Cursor relies on audience discovery from the PRM. We accept both server-specific and base MCP audiences on token verification.
Cursor uses cursor:// redirect URIs for its OAuth callback. Your DCR endpoint must accept custom URL schemes, not just https://.
Lambda Function URLs base64-encode form bodies. The POST /token request arrives with isBase64Encoded: true for application/x-www-form-urlencoded content. You must decode before parsing grant_type.
Lambda Function URL CORS doesn't accept OPTIONS in AllowMethods — preflight is handled automatically by the Function URL layer. Including it causes a CloudFormation validation error (AWS::EarlyValidation::PropertyValidation).
The WWW-Authenticate header gets remapped. Behind CloudFront + Lambda Function URL, it becomes x-amzn-remapped-www-authenticate. Cursor handles this correctly.
Dynamic Client Registration before pre-registered clients. Even though Cursor is pre-registered, it will attempt DCR first if it has no stored client info. The POST /register endpoint must work before /authorize will succeed.

What we implement from the MCP auth spec

Protected Resource Metadata (RFC 9728) — /.well-known/oauth-protected-resource
OAuth Authorization Server Metadata (RFC 8414) — /.well-known/oauth-authorization-server
OIDC Discovery 1.0 — /.well-known/openid-configuration (added in MCP 2025-11-25)
PKCE S256 (RFC 7636) — required for all clients
Dynamic Client Registration (RFC 7591) — POST /register
JWT access tokens (RS256) with JWKS endpoint at /jwks.json
Refresh token rotation for public clients per MCP spec § Authorization
Exact redirect URI matching

What we deliberately skip (for now)

Client ID Metadata Documents (CIMD) — recommended in the spec but no major MCP client uses them yet. We use DCR + pre-registration instead.
Resource Indicators on token requests — resource parameter (RFC 8707). Cursor doesn't send it; we bind audience at code issuance.
OAuth Client Credentials / Enterprise-Managed Authorization — these are MCP auth extensions, useful for headless/service access and enterprise IdP federation. Not needed for interactive Cursor flows.
SSE streaming — we proxy JSON-RPC request/response. Full Streamable HTTP with SSE resume (Last-Event-ID) is deferred.
Origin locking — the upstream MCP URL is still publicly reachable. Production deployments should add mTLS, a proxy-issued secret header, or network-level restriction. The MCP transport spec is explicit that the server must authenticate every request.

API endpoints

POST /mcp/{serverId} — MCP JSON-RPC proxy (Bearer token required)

GET /.well-known/oauth-protected-resource — Protected Resource Metadata

GET /.well-known/oauth-authorization-server — OAuth AS Metadata

GET /.well-known/openid-configuration — OIDC Discovery

GET /authorize — OAuth authorization (redirects to Google)

POST /token — Token exchange (code → JWT + refresh)

GET /jwks.json — RS256 public key set

POST /register — Dynamic Client Registration

Architecture

Single AWS Lambda (Node.js 22, arm64) behind CloudFront. DynamoDB single-table design for all state. No cold-start dependencies on external services — the RSA signing key is generated on first invocation and cached in Lambda memory.

Cursor ──HTTPS──▸ CloudFront ──▸ Lambda Function URL
                                    │
                      ┌─────────────┼──────────────┐
                      │             │              │
                 MCP Proxy    OAuth Server    Dashboard
                 /mcp/*       /authorize      /dashboard
                      │       /token
                      │       /register
                      ▼
              Upstream MCP Server
              (your Lambda Function URL)

JWT access tokens

Tokens are RS256-signed JWTs. The signing key is auto-generated and stored in DynamoDB. The public key is served at /jwks.json.

{
  "iss": "https://mcp-auth.cloud",
  "sub": "google-oauth2-subject-id",
  "aud": "https://mcp-auth.cloud/mcp/",
  "scope": "mcp:connect mcp:invoke",
  "email": "user@example.com",
  "exp": 1775231000,
  "iat": 1775227400,
  "jti": "unique-token-id"
}

User identity is keyed by Google sub (stable), not email (can change). Domain ACLs validate the hd claim per Google's token verification guidance.

Access control

Server owners configure access per server with two ACL types:

Email — exact match on the user's verified Google email.
Domain — matches any Google account with that email domain. Uses the domain portion of the email address at login.

The server owner always has implicit access. ACLs are checked both at authorization time (before issuing a code) and at proxy time (on every request).

MCP protocol version

Current spec version: 2025-11-25. The gateway propagates the MCP-Protocol-Version header to upstream and manages Mcp-Session-Id mapping between client and upstream sessions. See the spec changelog for what changed in each version.

Quick start

Sign in with your Google account.
Register your upstream MCP server URL.
Add email or domain ACLs for your users.
Share the config snippet or Cursor install deeplink.

{
  "mcpServers": {
    "my-server": {
      "url": "https://mcp-auth.cloud/mcp/srv_abc123..."
    }
  }
}

◆ MCP Auth