Authentication

OAuth 2.1 (recommended for AI clients)

The MCP server is planned to follow the MCP authorization specification: OAuth 2.1 with PKCE (S256) and public clients. Clients find everything they need from well-known metadata, so a user only has to paste the server URL.

1. Discover the authorization server

An unauthenticated request to https://review.expert/mcp returns 401 with a pointer to the Protected Resource Metadata (RFC 9728):

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://review.expert/.well-known/oauth-protected-resource"

{
  "resource": "https://review.expert/mcp",
  "authorization_servers": ["https://review.expert"],
  "scopes_supported": ["apps:read", "reviews:read", "replies:draft"],
  "bearer_methods_supported": ["header"]
}

The client then reads the Authorization Server Metadata (RFC 8414):

{
  "issuer": "https://review.expert",
  "authorization_endpoint": "https://review.expert/oauth/authorize",
  "token_endpoint": "https://review.expert/oauth/token",
  "registration_endpoint": "https://review.expert/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": ["apps:read", "reviews:read", "replies:draft"]
}

2. Register the client (Dynamic Client Registration)

Clients register themselves with RFC 7591 Dynamic Client Registration. No developer portal or manual client ID is needed.

POST /oauth/register
Content-Type: application/json

{
  "client_name": "My Review Agent",
  "redirect_uris": ["http://127.0.0.1:33418/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

3. Sign in or sign up, then consent

1. The client opens the authorization URL with a PKCE code challenge.
2. The person enters their email and the one-time code Review Expert sends them (the same email sign-in Review Expert uses today).
3. New users: Review Expert creates a team on the free Agent tier (proposed: 1 app, 500 tool calls/month). They can then connect an App Store or Google Play app in Review Expert.
4. A consent screen lists the client name, redirect URI and requested scopes. The person approves or denies.
5. The client exchanges the code for a short-lived access token and a refresh token. The token is bound to one team and to the MCP endpoint as its audience.

Team owners and admins will be able to see and revoke connected clients in Review Expert.

Scopes

API keys

For scripts, CI jobs and clients that only support a static header (for example Cursor), team owners and admins will be able to create API keys under Admin → Settings → API keys.

• Keys start with rx_live_ so secret scanners can detect leaked keys.
• Each key belongs to one team and carries the scopes chosen when it was created.
• Keys are stored hashed. The full key is shown once, at creation.
• Keys can be revoked at any time. Each key shows when it was last used.

POST https://review.expert/mcp
Authorization: Bearer rx_live_…
Content-Type: application/json
Accept: application/json, text/event-stream

Errors

• 401 — missing, expired or revoked token. Includes a WWW-Authenticate header.
• 403 — the token lacks the scope the tool needs (insufficient_scope).
• 429 — rate limit or monthly quota reached. See limits & pricing.