MCP OAuth Reference

How AGO’s OAuth 2.1 provider works and how to register a new MCP client.

AGO’s MCP server implements OAuth 2.1 with PKCE for clients that don’t support custom HTTP headers (e.g. Claude Web). Existing X-API-Key authentication continues to work unchanged for SDK / Zapier / CLI integrations.

Per-tenant URLs

All endpoints are tenant-scoped via subdomain:

Endpoint	Path
Authorization Server metadata (RFC 8414)	https://<tenant>.api.useago.com/.well-known/oauth-authorization-server
Protected Resource metadata (RFC 9728)	https://<tenant>.api.useago.com/.well-known/oauth-protected-resource
Authorize	https://<tenant>.api.useago.com/api/v1/oauth/authorize/
Token	https://<tenant>.api.useago.com/api/v1/oauth/token/
Revoke	https://<tenant>.api.useago.com/api/v1/oauth/revoke/

The MCP resource itself is https://<tenant>.api.useago.com/api/v1/mcp.

Supported flow

• Grant type: authorization_code
• PKCE: required (S256 only — plain rejected)
• Token format: opaque (not JWT)
• Access token TTL: 1 hour
• Refresh token TTL: 30 days, with rotation and a 30-second grace period (covers concurrent-refresh races from pipelined clients)
• Authorization code TTL: 60 seconds
• Public clients: yes — no client_secret required when token_endpoint_auth_method=none
• Per-tenant isolation: each tenant has its own database; a token issued in tenant A’s DB cannot be looked up from tenant B’s MCP URL — replay attempts return 401

What’s not (yet) supported

• Dynamic Client Registration (RFC 7591) — the registration_endpoint is intentionally absent from the metadata document. Register clients manually as below.
• Client credentials / device flow — only authorization-code is implemented.
• OIDC ID tokens — the resource model is OAuth 2.1, not OIDC.
• Token introspection (RFC 7662) — not exposed to third parties.

Register a new MCP client

If you build an MCP client (Cursor, Windsurf, an internal agent), email [e-mail] with:

• The product name (shown to end-users on the consent screen).
• A list of redirect URIs (HTTPS only, exact match).
• The scopes you’ll request by default.
• Whether you’re a public (no secret) or confidential (server-side, with secret) client.

We respond with a client_id. We’re tracking demand — once a few more clients ask we’ll ship Dynamic Client Registration.

Sample auth-code flow (curl)

# 1. Generate PKCE pair
verifier=$(openssl rand -base64 60 | tr -d '=+/' | cut -c1-64)
challenge=$(printf '%s' "$verifier" | openssl dgst -sha256 -binary | openssl base64 | tr -d '=' | tr '/+' '_-')

# 2. Open in a browser:
# https://acme.api.useago.com/api/v1/oauth/authorize/
#   ?client_id=claude-web
#   &redirect_uri=https://your-app/callback
#   &response_type=code
#   &scope=knowledge:read
#   &state=xyz
#   &code_challenge=$challenge
#   &code_challenge_method=S256
# After Allow, you receive ?code=AUTH_CODE&state=xyz at your redirect.

# 3. Exchange the code:
curl https://acme.api.useago.com/api/v1/oauth/token/ \
  -d grant_type=authorization_code \
  -d code=$AUTH_CODE \
  -d client_id=claude-web \
  -d redirect_uri=https://your-app/callback \
  -d code_verifier=$verifier

The full flow plus an MCP call is wrapped in scripts/oauth_smoke.sh in the AGO repository.

Refresh

curl https://acme.api.useago.com/api/v1/oauth/token/ \
  -d grant_type=refresh_token \
  -d refresh_token=$REFRESH_TOKEN \
  -d client_id=claude-web

Concurrent refresh: two requests with the same refresh_token arriving within 30 seconds both succeed. Outside that window, replaying an already-rotated refresh token revokes the entire chain (RFC 6749 §10.4 reuse detection).

Revoke

curl https://acme.api.useago.com/api/v1/oauth/revoke/ \
  -d token=$ACCESS_OR_REFRESH_TOKEN \
  -d client_id=claude-web

A revoked access token returns 401 on the next MCP call (no cache in MVP). Active SSE streams live until the client reconnects.