> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cometly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> OAuth 2.1 with PKCE for browser-based clients (CIMD or Dynamic Client Registration), or a personal access token for server-side agents. MCP-aware clients like Claude Desktop and Cursor handle OAuth automatically.

## TL;DR

You don't need to manage anything by hand. MCP-aware clients walk the full OAuth flow themselves the first time they hit the Cometly MCP endpoint:

1. The client sees a `401 Unauthorized` with a `WWW-Authenticate` header pointing at our OAuth discovery URL.
2. The client identifies itself — either via a hosted metadata document (CIMD) or by calling the registration endpoint (DCR).
3. The client opens your browser to the Cometly authorization page.
4. You log in, choose which Spaces to grant access to (one, several, or all of yours) and a default, and click **Approve**.
5. The client exchanges the resulting code for an access token covering those Spaces.

After that the client just sends `Authorization: Bearer <token>` on every tool call.

If you're **building a custom MCP client**, you have two registration paths: [CIMD](#client-id-metadata-document-cimd) (preferred — no registration call required) and [Dynamic Client Registration](#dynamic-client-registration) (fallback, e.g. for custom URI schemes). If you want the gritty detail, keep reading.

If you're connecting a **server-side agent** (headless script, CI job, backend service — no browser), skip OAuth entirely and use a [personal access token](#server-side-agents-pat) instead.

## Endpoints

Cometly is its own authorization server. There's no third-party identity provider in the middle.

| Endpoint | URL |
| - | - |
| Protected resource metadata (RFC 9728) | `https://app.cometly.com/.well-known/oauth-protected-resource/{path}` |
| Authorization server metadata (RFC 8414) | `https://app.cometly.com/.well-known/oauth-authorization-server/{path}` |
| Dynamic client registration | `POST https://app.cometly.com/mcp/oauth/register` |
| Authorization (browser) | `GET https://app.cometly.com/mcp/oauth/authorize` |
| Token exchange | `POST https://app.cometly.com/mcp/oauth/token` |
| MCP server (resource) | `https://app.cometly.com/mcp` |

We expose **both** the path-prefix (RFC 9728) and path-suffix (RFC 8414) `.well-known` URL variants because different clients implement different revisions of the spec. Claude Desktop uses the prefix form; Cursor uses the suffix form. Both resolve to the same metadata. The root protected-resource document (`/.well-known/oauth-protected-resource`, no path) describes `https://app.cometly.com/mcp`, and the 401 challenge on that URL carries `WWW-Authenticate: Bearer realm="mcp", resource_metadata="https://app.cometly.com/.well-known/oauth-protected-resource/mcp"`.

The older per-Space URL, `https://app.cometly.com/mcp/{space_id}/public-api`, is kept as a legacy alias so existing connections keep working. `https://app.cometly.com/mcp/chatgpt` is the same server, except that `initialize`, `ping`, `tools/list`, and `notifications/initialized` are answered without a credential so the ChatGPT Apps directory can list the tools; every other call needs a token. Give ChatGPT that URL when you add Cometly as a custom connector, too.

## Discovery metadata

Hitting the auth-server metadata endpoint returns:

```json theme={null}
{
  "issuer": "https://app.cometly.com",
  "authorization_endpoint": "https://app.cometly.com/mcp/oauth/authorize",
  "token_endpoint": "https://app.cometly.com/mcp/oauth/token",
  "registration_endpoint": "https://app.cometly.com/mcp/oauth/register",
  "response_types_supported": ["code"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["mcp:use"],
  "grant_types_supported": ["authorization_code"],
  "token_endpoint_auth_methods_supported": ["none"],
  "client_id_metadata_document_supported": true
}
```

Protected-resource documents also return `"bearer_methods_supported": ["header"]`. PKCE with `S256` is required. There's no implicit grant, no password grant, no client-credentials grant — just authorization code with PKCE.

## Client ID Metadata Document (CIMD)

CIMD is the preferred registration path for new custom MCP clients. Instead of calling `/mcp/oauth/register` to get a client ID, you host a JSON document at an `https://` URL and use that URL itself as your `client_id` — no registration request needed.

Support is advertised via `client_id_metadata_document_supported: true` in the [discovery metadata](#discovery-metadata). If that field is absent or `false`, fall back to [Dynamic Client Registration](#dynamic-client-registration).

### Metadata document

Host a JSON file at any stable `https://` URL with a non-root path (for example, `https://app.example.com/oauth/client-metadata.json`). The document must include:

| Field | Required | Description |
| - | - | - |
| `client_id` | Yes | Must exactly equal the URL the document is hosted at. |
| `client_name` | Yes | Shown verbatim on the consent screen. |
| `redirect_uris` | Yes | Array of allowed redirect URIs — see rules below. |
| `token_endpoint_auth_method` | Yes | Must be `"none"`. Public clients only; `private_key_jwt` is not yet supported. |

All other fields (`client_uri`, `grant_types`, `response_types`) are accepted and recorded but not enforced.

```json theme={null}
{
  "client_id": "https://app.example.com/oauth/client-metadata.json",
  "client_name": "Example MCP Client",
  "client_uri": "https://app.example.com",
  "redirect_uris": ["https://app.example.com/callback", "http://127.0.0.1:3000/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

On the consent screen, Cometly shows the verified client domain alongside `client_name`. Clients whose only redirect URIs are loopback addresses receive an advisory notice on the consent screen.

### Accepted `redirect_uris` for CIMD clients

Each URI in the document must satisfy one of two rules:

| Category | Examples | Rule |
| - | - | - |
| Loopback | `http://127.0.0.1:33333/callback`, `http://localhost/cb` | Any port, any path. RFC 8252 loopback normalization applies. |
| Same-origin https | `https://app.example.com/callback` | The redirect URI origin must exactly match the `client_id` URL origin (same scheme, host, and port). Cross-origin https URIs are rejected. |

**Custom URI schemes** (e.g. `cursor://`, `vscode://`) are **not** accepted for CIMD clients. If your client uses a custom scheme, use [Dynamic Client Registration](#dynamic-client-registration) instead — the custom-scheme allowlist applies only to DCR.

The `redirect_uri` you send on `/authorize` and `/token` must exactly match one of the URIs in the document (loopback port normalization per RFC 8252 applies).

### Document fetching and caching

On every `/authorize` request with a URL-shaped `client_id`, Cometly fetches and validates the metadata document. The fetch is:

* **SSRF-guarded** — private, loopback, link-local, and cloud-metadata IPs are refused.
* **TLS-verified** — the certificate must be valid; redirects are not followed by default.
* **Rate-limited and size-capped** — oversized or excessively frequent responses are rejected.

Cometly caches the validated document per `client_id` URL, honoring `Cache-Control: max-age` up to a 24-hour ceiling (default window 15 minutes). Deploy an updated document and wait up to 24 hours for all caches to clear, or set a shorter `max-age` on your server's response.

## Dynamic client registration

Dynamic Client Registration (RFC 7591) is the fallback path when CIMD isn't suitable — for example when your client uses a custom URI scheme (`cursor://`, `vscode://`) that CIMD doesn't accept, or when you can't host a metadata document at a stable https URL.

`POST /mcp/oauth/register` with the client's metadata. Minimal example:

```json theme={null}
{
  "client_name": "My MCP Client",
  "redirect_uris": ["http://127.0.0.1:33333/callback"],
  "token_endpoint_auth_method": "none"
}
```

Returns a `client_id` you'll use for the authorization request. There is no `client_secret` — Cometly's MCP server treats every client as a public client and relies on PKCE for security.

### Accepted `redirect_uris`

The redirect URI is validated at registration. Each URI must fall into one of three accepted categories; redirect URIs that don't match are rejected. This allowlist applies to DCR clients only — [CIMD clients](#accepted-redirect_uris-for-cimd-clients) use a same-host rule instead.

| Category | Examples | Use case |
| - | - | - |
| Loopback | `http://127.0.0.1:33333/callback`, `http://localhost/cb` | Native desktop clients |
| `https://` to an allowed host | `https://claude.ai/api/mcp/auth_callback` | Hosted web clients — see [Default allowed https hosts](#default-allowed-https-hosts) below |
| Well-known custom scheme | `cursor://...`, `vscode://...`, `claude-desktop://...`, `com.example.app:/oauth2redirect` | Desktop and native apps |

### Default allowed https hosts

These hosts are accepted for DCR clients out of the box. If you need a host that isn't listed, contact support: [support@cometly.com](mailto:support@cometly.com). (CIMD clients don't need to be on this list — they use the same-host rule described above.)

| Host(s) | Client |
| - | - |
| `claude.ai`, `claude.com` | Anthropic Claude (web, desktop, mobile) |
| `chatgpt.com`, `chat.openai.com` | OpenAI ChatGPT |
| `cursor.com`, `www.cursor.com` | Cursor web agents |
| `vscode.dev`, `insiders.vscode.dev` | VS Code for the Web / github.dev (desktop VS Code uses loopback + `vscode://`) |
| `grok.com` | xAI Grok |
| `gemini.google.com` | Google Gemini |
| `perplexity.ai`, `www.perplexity.ai` | Perplexity |

### Accepted `client_name`

`client_name` is shown verbatim on the consent screen, so it's validated to prevent impersonation and UI hijacking:

* Maximum 120 characters.
* No control characters (`\x00–\x1f`, `\x7f`).
* Names that contain `cometly` as a standalone word (case-insensitive, word/whitespace/hyphen/underscore boundaries) are rejected to keep malicious clients from passing themselves off as Cometly itself.

### Rate limits

`POST /mcp/oauth/register` is throttled to **120 registrations per hour per IP**. Legitimate clients register once per install, and hosted clients (claude.ai, chatgpt.com) share a few egress IPs, so this leaves headroom for many users behind one IP while making it impractical to flood the registration table. Exceeded requests return `429 temporarily_unavailable` with an RFC 7591 error body.

## Authorization flow

This flow is the same whether your `client_id` is an opaque string from DCR or an https URL from CIMD.

1. Generate a PKCE `code_verifier` and the matching `code_challenge` (`SHA256(verifier)`, base64url, no padding).

2. Redirect the user (in their browser) to:

   ```
   https://app.cometly.com/mcp/oauth/authorize
     ?response_type=code
     &client_id={client_id}
     &redirect_uri={redirect_uri}
     &code_challenge={code_challenge}
     &code_challenge_method=S256
     &state={random}
     &scope=mcp:use
   ```

   You can also send `&resource=https://app.cometly.com/mcp` (RFC 8707). It's optional, and when present it must be one of Cometly's MCP URLs. A legacy per-Space URL locks the consent screen to that Space.

3. The user logs in (if not already), then chooses what to grant and clicks **Approve**. A user who belongs to one Space just sees it. A user who belongs to several chooses **All my spaces** (every Space they belong to, including ones they're added to later) or **Choose spaces** (tick the ones to include), and picks a **default Space**, the one tools use when a call doesn't name a Space. Viewers are told the connection will be read-only.

4. Cometly redirects back to your `redirect_uri` with `?code={code}&state={state}`.

5. Exchange the code:

   ```bash theme={null}
   curl -X POST https://app.cometly.com/mcp/oauth/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code" \
     -d "code={code}" \
     -d "redirect_uri={redirect_uri}" \
     -d "client_id={client_id}" \
     -d "code_verifier={code_verifier}"
   ```

   Response:

   ```json theme={null}
   {
     "access_token": "1|abc...",
     "token_type": "Bearer",
     "expires_in": null,
     "scope": "mcp:use"
   }
   ```

   The `scope` is always `mcp:use`. The granted Spaces are carried by the token's ability (see [Scopes](#scopes)), not by this field. Tokens don't expire and there is no refresh token.

## Server-side agents (PAT)

The [Authorization flow](#authorization-flow) above is the right default for MCP-aware clients with a browser. If you're building a **server-side agent** (a headless script, a CI job, a backend service), there's no human at a browser to click **Approve**. For those cases, generate a personal access token (PAT) in the Cometly dashboard and send it as a bearer header.

A personal access token behaves exactly like an OAuth-issued token: it's tied to your user account, works for one Space only (tokens generated on the settings page are always single-Space; multi-Space grants come from the OAuth consent screen), and your access to that Space is re-checked on every request. The only difference is how you obtain one. Every member of a Space can generate one.

### Generate a token

Before you start, make sure you're signed in to Cometly and are a member of the target Space. If you're a Viewer, your tokens are always [read-only](#read-only-tokens).

1. Open **Settings → Integrations → MCP** in your Cometly dashboard.
2. Under **MCP Access Tokens**, enter a name for the token (e.g. `CI Agent`) and tick **Read-only** if the agent should only read data (Viewers see it checked and locked; see [Read-only tokens](#read-only-tokens)), then click **Generate Token**.
3. Copy the token right away. For security reasons, it isn't shown again. A ready-to-paste config snippet is displayed alongside it.

### Configure your agent

The token works with any MCP client that supports `type: http` servers with bearer auth. Minimal `.mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "cometly-agent": {
      "type": "http",
      "url": "https://app.cometly.com/mcp",
      "headers": {
        "Authorization": "Bearer 1|abc..."
      }
    }
  }
}
```

If you're calling the MCP endpoint directly (no MCP client library), see [Calling the MCP server](#calling-the-mcp-server). The `Authorization: Bearer` header is the only difference from an OAuth-issued token.

### Limits

* You can generate tokens on this page until you hold **25 MCP tokens for the Space**. Tokens issued to OAuth clients (Cursor, Claude Desktop, etc.) count toward that number, so if you hit the limit, revoke tokens you no longer use from the same page.
* The token works only for the Space you generated it in. A generated token can't be widened to other Spaces.
* Token names are limited to 120 characters and can't contain control characters. The name is only a label for the list on the settings page; it has no effect on what the token can do.
* Tokens don't expire. Revoke them when an agent is decommissioned (see [Revoking access](#revoking-access)).

### Read-only tokens

A read-only token can look at your data but can't change it. With one, the write tools (`update_contact`, `update_company`, `update_event`) are hidden from `tools/list`, and calling one returns a JSON-RPC "Tool not found" error. Every other tool, resource, and prompt works the same, and the server `instructions` returned by `initialize` tell the client the connection is read-only.

* Read-only tokens appear in the same list with a **Read-only** badge, count toward the same 25-token limit, and are revoked the same way.
* A token can't be converted. Existing tokens keep full access; to get a read-only one, generate a new token.
* OAuth-connected clients (Claude, Cursor, ChatGPT, and so on) follow your role. A Viewer's connection is read-only, and the consent screen says so. Every other role gets full access.
* A Viewer's connection (token or OAuth) also leaves out the contact and company tools, and `search_workspace` skips contacts and companies for it. The app hides the Contacts and Companies pages from Viewers (`space:see_journeys`), and MCP shows a role the same data as the app does. Calling one of those tools returns a "Tool not found" error.
* The role is re-checked on every write call, so a member demoted to Viewer loses the write tools immediately.

## Calling the MCP server

Once you have an access token, every JSON-RPC call to the MCP endpoint carries it:

```bash theme={null}
curl -X POST https://app.cometly.com/mcp \
  -H "Authorization: Bearer 1|abc..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

You don't put a Space ID in the URL: the token carries the Spaces it was approved for.

Every tool accepts an optional `space_id` argument (a string, the numeric ID from [`list_my_spaces`](https://docs.cometly.com/mcp/tools/list-my-spaces)):

```bash theme={null}
curl -X POST https://app.cometly.com/mcp \
  -H "Authorization: Bearer 1|abc..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_workspace_context","arguments":{"space_id":"456"}}}'
```

* Without `space_id`, the call runs in the connection's **default Space**. Custom field and event labels in tool descriptions describe the default Space.
* A `space_id` the token's grant doesn't cover is refused with an `[authorization_error]` tool result (HTTP `200`, `isError: true`) telling the agent to reconnect and include that Space.
* Membership, your role in that Space, and the team's plan are re-checked on every call for the Space the call targets.
* If you still call a legacy `/mcp/{space_id}/public-api` URL, the path names the Space: it **must** be covered by the token, and a different `space_id` argument is refused with the same `[authorization_error]` tool result.

## Scopes

There is one MCP scope on the wire (`mcp:use`). What a token may reach is encoded in its single ability, `mcp_space:` followed by the granted Spaces:

| Ability | What it grants |
| - | - |
| `mcp_space:42` | One Space. Call any tool against Space 42 (including the three `update_*` write tools). |
| `mcp_space:42,7,9` | The chosen Spaces. The first (42) is the default; tools can target 7 and 9 with `space_id`. |
| `mcp_space:42,*` | Every Space the user belongs to, now and later. 42 is the default. |
| any of the above plus `:read` (for example `mcp_space:42:read`) | Same Spaces, but the three `update_*` write tools are unavailable. Issued to [read-only tokens](#read-only-tokens) generated on the MCP page (always, for a Viewer). An OAuth connection made by a Viewer is read-only through the live role check instead, so a later promotion applies without reconnecting. |

The Spaces are chosen on the consent screen. The ability only says which Spaces the token may name. It never grants more than your account can open: membership, role, and plan are checked live on every call for the target Space. An all-Spaces grant therefore follows your memberships: add yourself to a Space and it becomes reachable, get removed and it's refused.

A user with different roles across the granted Spaces gets a full-access token, and each call is allowed or refused by the role in the Space it targets (a Viewer role there still can't write).

## Revoking access

You can revoke any MCP token for a Space — whether issued via OAuth (Cursor, Claude Desktop, etc.) or generated as a PAT — from a single list:

1. Open **Settings → Integrations → MCP** in your Cometly dashboard.
2. Under **Server-side (headless) agents**, find the token you want to revoke. OAuth-issued tokens appear here too, named after the client and the Spaces they cover (e.g. `MCP: Cursor (Acme Marketing)`, `MCP: Cursor (Acme Marketing +2)`, or `MCP: Cursor (All spaces)`).
3. Click **Revoke**.

A token that covers several Spaces is listed on every Space it covers, with an **All spaces** or **N spaces** badge. Revoking it from any one of them revokes it everywhere.

The next tool call from that token gets `401 Unauthorized`. OAuth clients will walk the auth flow again on next launch; PAT clients will need a fresh token generated for them.

Removing a user from a Space immediately cuts off every MCP token they hold for that Space — there's no separate cleanup step. A multi-Space token keeps working for the Spaces they still belong to.

## Common errors

| Status | Meaning | Recovery |
| - | - | - |
| `401` | No / invalid / expired token. | Walk the OAuth flow again. The `WWW-Authenticate` header includes the discovery URL. |
| `200` with an `[authorization_error]` tool result | A tool call was refused: the `space_id` you passed isn't in the token's grant, the token's grant doesn't cover the Space in a legacy `/mcp/{space_id}/public-api` URL (or a different `space_id` was sent on that URL), the user is no longer a member of the target Space, the role lost the permission a tool needs (contacts and companies need `space:see_journeys`), or the Space's team has no API access. Refusals inside a tool call come back as a tool result with `isError: true` and the `[authorization_error]` envelope, not as an HTTP 403. | Use `https://app.cometly.com/mcp`, or reconnect and include the Space on the consent screen (or pick a Space `list_my_spaces` marks `granted`). For the plan case, reach out to your Cometly admin or contact sales. |
| `200` with a JSON-RPC `error` (`-32602`, "Tool not found") | The tool isn't offered to this connection: a write tool on a read-only connection (a [read-only token](#read-only-tokens), or a Viewer), or a contact or company tool for a Viewer. | Use a connection whose role or token has the tool; Viewers can't write. |
| `403` (`forbidden_origin`) | A browser request came from an origin that isn't allowed. Hosted clients send no origin; claude.ai, claude.com, chatgpt.com, chat.openai.com, platform.openai.com, and loopback addresses are allowed. | Call the server from an allowed client, or from a server-side process. |
| `429` | Rate limit exceeded. | Back off. See [Rate Limits & Errors](https://docs.cometly.com/mcp/rate-limits-and-errors.md). |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.