Skip to main content

OAuth Overview

The Perspective MCP HTTP endpoint (POST https://api.perspective.co/mcp) requires an OAuth2 Bearer token on every request. For MCP clients that implement the MCP authorization spec, the server exposes the discovery and proxy endpoints needed to complete the flow automatically — most clients (such as Claude Code) handle this without any manual steps beyond signing in.

Why OAuth?​

The HTTP endpoint is a multi-tenant service. OAuth2 lets each connecting client obtain a scoped token tied to a specific Perspective workspace, without the user ever handing their credentials to the MCP client.

High-level flow​

The flow follows the MCP protected-resource model, which layered on top of standard OAuth2 Authorization Code + PKCE:

1. Unauthenticated request → 401​

When an MCP client calls POST https://api.perspective.co/mcp without a Bearer token (or with an invalid one), the server responds with 401 Unauthorized and a WWW-Authenticate header that points the client to the protected-resource discovery document:

WWW-Authenticate: Bearer resource_metadata="https://api.perspective.co/.well-known/oauth-protected-resource"

If the token was present but invalid, the header additionally carries error="invalid_token" and a description.

2. Fetch protected-resource metadata​

The client fetches GET https://api.perspective.co/.well-known/oauth-protected-resource. The response identifies the resource and lists its authorization servers:

{
"resource": "https://api.perspective.co",
"authorization_servers": ["https://api.perspective.co"],
"scopes_supported": ["offline_access", "openid"],
"bearer_methods_supported": ["header"],
"resource_documentation": "https://developers.perspective.co"
}

3. Fetch authorization-server metadata​

The client fetches GET https://api.perspective.co/.well-known/oauth-authorization-server. This returns the full server metadata, including all the endpoints the client needs to complete the flow. Its issuer is the MCP server origin, the same value as authorization_servers[0] in step 2, so clients that check RFC 8414 issuer equality (Codex, mcp-remote and others) accept it:

{
"issuer": "https://api.perspective.co",
"authorization_endpoint": "https://api.perspective.co/oauth/authorize",
"token_endpoint": "https://api.perspective.co/oauth/token",
"jwks_uri": "https://authenticate.perspective.co/.well-known/jwks.json",
"registration_endpoint": "https://api.perspective.co/oauth/register",
"response_types_supported": ["code"],
"grant_types_supported": ["authorization_code", "refresh_token"],
"token_endpoint_auth_methods_supported": ["none"],
"code_challenge_methods_supported": ["S256"],
"scopes_supported": ["offline_access", "openid"]
}

4. (Optional) Dynamic client registration​

If the client does not already have a client_id, it can register itself by calling POST https://api.perspective.co/oauth/register with a JSON body that includes redirect_uris. The server returns a client_id (shared across all dynamic registrations) along with the client metadata. This step is optional — clients that already have a client_id skip it.

5. Authorization-code flow (via Auth0)​

The client redirects the user to GET https://api.perspective.co/oauth/authorize with standard OAuth2 parameters (client_id, redirect_uri, code_challenge, etc.). The server checks that redirect_uri is on its allowlist of trusted client callbacks, then proxies the request to the configured Auth0 tenant, appending the required audience and connection parameters. After the user authenticates, Auth0 sends the authorization code to the server's /oauth/callback, which relays it to the client's redirect_uri.

The client exchanges the code for tokens at POST https://api.perspective.co/oauth/token, which the server forwards to Auth0. Requesting the offline_access scope also returns a refresh token.

6. Authenticated MCP request​

The client retries POST https://api.perspective.co/mcp with the obtained token:

Authorization: Bearer <token>

The server validates the token via Auth0's JWKS endpoint, checking the token's issuer (the iss claim, which is the Auth0 domain https://authenticate.perspective.co/, not the metadata issuer from step 3), audience, algorithm (RS256), and that the token identifies a Perspective user, their workspace and its subscription (details Perspective adds when the user signs in). On success the request proceeds normally.

Most clients handle this automatically​

MCP clients that implement the MCP authorization spec — including Claude Code — perform all of the above steps without manual configuration. When you add the Perspective MCP server and connect for the first time, the client discovers the OAuth endpoints, registers if necessary, and opens a browser window for you to sign in. After that, it stores the token and refreshes it automatically.

You do not need to call any of these endpoints yourself unless you are building a custom MCP client or debugging the OAuth flow.