MCP OAuth (remote clients)

The MCP gateway lets you call governed tools over JSON-RPC with an API key. MCP OAuth lets a remote MCP client — e.g. Claude.ai's custom connectors — discover Nolixan, run an OAuth 2.1 consent flow, and receive a scoped token, all without you sharing an API key. Nolixan acts as both the authorization server and the resource server.

Discovery

Clients discover the endpoints from standard well-known documents (no auth):

The flow

1. Dynamic client registration (RFC 7591) — the client self-registers:

   curl -X POST https://your-host/api/v1/oauth-server/register \
     -H "Content-Type: application/json" \
     -d '{ "client_name": "Claude", "redirect_uris": ["https://claude.ai/api/mcp/callback"] }'
   # → { "client_id": "…", "client_secret": "…"? }

   Redirect URIs must be HTTPS. Public PKCE clients receive no secret.

2. Authorize (OAuth 2.1, PKCE S256 required) — GET /api/v1/oauth-server/authorize?response_type=code&client_id=…&redirect_uri=…&code_challenge=…&code_challenge_method=S256&scope=…&state=…. Nolixan validates the client and redirect URI and shows a consent screen where the user picks the environment and approves scopes.

3. Token (RFC 6749, form-encoded) — exchange the code (with the PKCE code_verifier) for an opaque access token + rotating refresh token:

   curl -X POST https://your-host/api/v1/oauth-server/token \
     -d grant_type=authorization_code -d code=… -d redirect_uri=… \
     -d client_id=… -d code_verifier=…
   # → { "access_token": "…", "refresh_token": "…", "token_type": "Bearer", "expires_in": … }

4. Call tools — the client uses the access token as a bearer token against the MCP endpoint. The token's scope is bound to the same least-privilege grant allowlist as API keys, so the client only sees and calls what it was granted.

Opaque tokens & revocation

Access tokens are opaque (not JWTs), so they can be revoked instantly — there's no signature to keep honoring until expiry.

curl -X POST https://your-host/api/v1/oauth-server/revoke \
  -d token=… -d token_type_hint=access_token   # RFC 7009, always 200

Users can review and revoke connected apps:

Because writes are still governed by policy, default-deny on writes correctly hides write tools from a freshly connected client until you allow them. Full security notes: docs/MCP_OAUTH_SECURITY.md; connection walkthrough: docs/MCP_OAUTH_CONNECT.md.