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 address access is sent to: the origin of the redirect URI this request will deliver the code to. This is the line to check.
• The name the application registered (for example, “Claude”), shown as a claim. Pathbound doesn’t verify application names.
• What the connection will hold, one row per permission. “Always included” rows are the read and CRM-edit access every connection gets. “Also requested” rows are the opt-in writes the application asked for: sending email and acting in connected tools (actions:write), spending enrichment credits (enrichment:write), and creating streaming automations (streams:write).
• Which tools are on now. Rows whose tools a workspace admin toggles say which are on in your workspace. An opt-in that is off is still granted: if an admin turns the tool on later, the connection can use it without asking again. Stream changes are marked admins only for members, because the API refuses them whatever the token holds.
• Which account and workspace. The connection reaches the workspace of the account you are signed in with, shown at the bottom of the screen. Use another account signs you out and brings you back to the same request once you sign in with another one. The request is valid for five minutes; after that, start the connection again from the application.

The list is built by the Pathbound API from the same definition that issues and enforces the token, so it shows exactly what the connection will hold. Only authorize applications you trust: the JWT issued at the end of this flow grants those permissions 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.

Every connection made through the MCP flow can read and write the workspace’s own records:

contacts:read, contacts:write
companies:read, companies:write
deals:read, deals:write
events:read
streams:read
knowledge:read, knowledge:write

Three more scopes are granted only when the client asks for them and you approve them on the consent screen, which lists exactly what the connection will hold:

actions:write       sending email and acting in connected tools
enrichment:write    enrichment and prospecting, which spend provider credits
streams:write       creating and changing automations (workspace admins only)

A scope does not switch a tool on by itself. The knowledge, streaming and action tools also need their switch turned on under MCP Tools in the dashboard, and an agent can never delete a contact or a company whatever it was granted.

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/settings/api-keys (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/Resend sends and Apollo sequence drafting, enrollment, and single-email actions) 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.
• A key without actions:write also sees none of the other optional tool groups (enrichment, streaming, knowledge), even with their own scopes, because the MCP server reads the workspace’s tool switches through an endpoint that needs that scope. Give a headless MCP client actions:write if it should use any of them.
• 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/settings/api-keys. Tool calls fail immediately; the MCP transport stops accepting the key within a minute.

Users can revoke MCP access from MCP Tools → Disconnect all in the Pathbound dashboard. It takes effect at once: every MCP token issued to that user stops working, and each AI client asks them to sign in again. API keys are not affected; revoke a key under Settings → API keys.