MCP — Authentication

The MCP server accepts two kinds of credentials:

• OAuth 2.0 with Pathbound’s native login — for interactive clients (Claude.ai) where a human can complete a browser flow. The MCP server delegates the actual login to Pathbound’s web app and brokers the resulting JWT into MCP-shaped OAuth tokens.
• REST API keys — for headless clients (hosted MCP tool runners, server-side agents, pipelines) that can only send a static Authorization header.

┌──────────────┐                  ┌──────────────────┐                ┌────────────────┐
│  MCP client  │                  │  mcp.pathbound   │                │ api.pathbound  │
│ (Claude.ai)  │                  │      .ai          │                │      .ai       │
└──────┬───────┘                  └────────┬─────────┘                └────────┬───────┘
       │                                   │                                   │
       │  1. GET /authorize                │                                   │
       │ ────────────────────────────────▶ │                                   │
       │                                   │  2. 302 to                        │
       │                                   │     /mcp/authorize                │
       │                                   │ ────────────────────────────────▶ │
       │                                   │                                   │
       │                                   │      User logs in (or already     │
       │                                   │      has a Pathbound session)     │
       │                                   │                                   │
       │                                   │  3. 302 back with one-time code   │
       │ ◀──────────────────────────────── │ ◀──────────────────────────────── │
       │                                   │                                   │
       │  4. POST /token { code }          │                                   │
       │ ────────────────────────────────▶ │  5. POST /mcp/token { code }      │
       │                                   │ ────────────────────────────────▶ │
       │                                   │  6. JWT (90d default)             │
       │                                   │ ◀──────────────────────────────── │
       │  7. MCP access_token + refresh    │                                   │
       │ ◀──────────────────────────────── │                                   │
       │                                   │                                   │
       │  8. tool calls (Bearer)           │                                   │
       │ ────────────────────────────────▶ │  9. Backend V1 calls (JWT)        │
       │                                   │ ────────────────────────────────▶ │
       │                                   │ ◀──────────────────────────────── │
       │ ◀──────────────────────────────── │                                   │

1. The MCP client (Claude.ai) hits the MCP server’s /authorize endpoint.
2. The MCP server has no local login form — it 302s to https://api.pathbound.ai/mcp/authorize.
3. If the user has an active Pathbound session, the backend issues a one-time code immediately and redirects back to the MCP server. If not, the user is sent through the normal Pathbound login (with 2FA if configured), then redirected. 4–7. The MCP server exchanges the code for a JWT via POST /mcp/token on the backend, then maps that JWT onto its own MCP-shaped OAuth access and refresh tokens which it returns to the client. 8–9. Subsequent MCP tool calls use the MCP access token; the MCP server forwards them to the backend as the underlying JWT.

Before the backend issues the one-time code in step 3, the user sees a consent screen showing:

• The requesting application’s name (as registered with the MCP server — e.g. “Claude”).
• The origin the request came from.
• The exact scopes the application is asking for, one row per permission.

Always check that the application name and origin match the tool you intended to authorize. Only authorize applications you trust — the JWT issued at the end of this flow grants the requested scopes against your tenant for the full token lifetime below.

If you see a “could not be verified” error on the consent screen, the application’s authorization request failed integrity validation between the MCP server and the backend — close the tab and reconnect from inside the application rather than retrying the same link.

These are the operator defaults; your Pathbound deployment may set different values. When an access token expires, the client uses its refresh token to get a new one without going through the full browser flow again.

JWTs issued via the MCP flow cover the full public V1 surface:

contacts:read, contacts:write
companies:read, companies:write
events:read

If you need a tighter scope set — for example, a read-only integration — connect with a scoped API key instead.

Server-side MCP clients — OpenAI and Anthropic hosted tool runners, schedulers, CI jobs — can’t open a browser or refresh OAuth tokens. They authenticate by sending a tenant REST API key as a static bearer token on every request:

Authorization: Bearer sk_your_api_key

No OAuth handshake, no token expiry to manage — the key works until you revoke it.

1. Create a key at app.pathbound.ai/rest-api (tenant admins only), selecting only the scopes the agent needs — contacts:read and events:read make a good read-only analyst.
2. Configure your MCP client with the server URL https://mcp.pathbound.ai/mcp and the key as its authorization/bearer token.

Example with the Anthropic API’s MCP connector:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.pathbound.ai/mcp",
      "name": "pathbound",
      "authorization_token": "sk_your_api_key"
    }
  ]
}

• The key’s scopes are enforced on every tool call, exactly as on the REST API. A contacts:read key can call list_contacts but gets a descriptive permission error from update_contact naming the missing scope.
• Write-action tools (gmail_send_email, the Resend send tools) additionally require the opt-in actions:write scope and the corresponding tool toggle in your integration settings. Keys without actions:write never see those tools listed.
• Actions performed with a key are attributed as api_key:<key_id> in the action log.
• If your tenant has MCP PII redaction enabled, it applies to API-key MCP sessions the same as OAuth ones. Direct REST API calls with the same key remain unredacted.

Deactivate or delete the key at app.pathbound.ai/rest-api. Tool calls fail immediately; the MCP transport stops accepting the key within a minute.

Users can revoke MCP access from Settings → Connected Apps in the Pathbound dashboard. Revoking immediately invalidates the underlying JWT, which invalidates all MCP tokens that wrap it.