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"],
  "bearer_methods_supported": ["header"]
}

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:

{
  "issuer": "https://<auth0-tenant>.auth0.com/",
  "authorization_endpoint": "https://api.perspective.co/oauth/authorize",
  "token_endpoint": "https://<auth0-tenant>.auth0.com/oauth/token",
  "jwks_uri": "https://<auth0-tenant>.auth0.com/.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"]
}

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 proxies this to the configured Auth0 tenant, appending the required audience and connection parameters. After the user authenticates, Auth0 issues an authorization code.

The client exchanges the code for tokens at the Auth0 token endpoint (POST https://<auth0-tenant>.auth0.com/oauth/token). 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 issuer, audience, algorithm (RS256), and that the token's https://perspective.co/user_metadata claim contains both a companyId and a subscriptionId. 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.