Skip to content
Pathbound DOCS
Sign in Get an API key →

MCP — Authentication

The MCP server uses OAuth 2.0 with Pathbound’s native login. There is no API key for MCP clients. The MCP server delegates the actual login to Pathbound’s web app and brokers the resulting JWT into MCP-shaped OAuth tokens.

Flow

Section titled “Flow”
┌──────────────┐                  ┌──────────────────┐                ┌────────────────┐
│  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.

Token lifetime

Section titled “Token lifetime”
TokenDefault lifetime
Backend JWT90 days (MCP_TOKEN_EXPIRY_DAYS)
MCP access token30 days (MCP_ACCESS_TOKEN_TTL_DAYS)
MCP refresh token180 days (MCP_REFRESH_TOKEN_TTL_DAYS)

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.

Scopes

Section titled “Scopes”

JWTs issued via the MCP flow get a broad scope set by design — they need to be able to drive most of the API:

agents:read, agents:write, agents:trigger, agents:approve
actions:read, actions:write
contacts:read, contacts:write
companies:read, companies:write
segments:read
events:read
identities:read

Notably absent: identities:write (you can read identities to pick a sender, but you can’t create or modify them via MCP) and segments:write (reserved for future use).

If you need a tighter scope set than this — for example, a read-only Claude integration — use the REST API with a scoped API key instead.

Revoking access

Section titled “Revoking access”

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.