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:- The client sees a
401 Unauthorizedwith aWWW-Authenticateheader pointing at our OAuth discovery URL. - The client identifies itself — either via a hosted metadata document (CIMD) or by calling the registration endpoint (DCR).
- The client opens your browser to the Cometly authorization page.
- You log in, choose which Spaces to grant access to (one, several, or all of yours) and a default, and click Approve.
- The client exchanges the resulting code for an access token covering those Spaces.
Authorization: Bearer <token> on every tool call.
If you’re building a custom MCP client, you have two registration paths: CIMD (preferred — no registration call required) and 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 instead.
Endpoints
Cometly is its own authorization server. There’s no third-party identity provider in the middle.
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:"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. If that field is absent or false, fall back to Dynamic Client Registration.
Metadata document
Host a JSON file at any stablehttps:// URL with a non-root path (for example, https://app.example.com/oauth/client-metadata.json). The document must include:
All other fields (
client_uri, grant_types, response_types) are accepted and recorded but not enforced.
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:
Custom URI schemes (e.g.
cursor://, vscode://) are not accepted for CIMD clients. If your client uses a custom scheme, use 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.
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:
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 use a same-host rule instead.
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. (CIMD clients don’t need to be on this list — they use the same-host rule described above.)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
cometlyas 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 yourclient_id is an opaque string from DCR or an https URL from CIMD.
-
Generate a PKCE
code_verifierand the matchingcode_challenge(SHA256(verifier), base64url, no padding). -
Redirect the user (in their browser) to:
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. - 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.
-
Cometly redirects back to your
redirect_uriwith?code={code}&state={state}. -
Exchange the code:
Response:The
scopeis alwaysmcp:use. The granted Spaces are carried by the token’s ability (see Scopes), not by this field. Tokens don’t expire and there is no refresh token.
Server-side agents (PAT)
The 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.- Open Settings → Integrations → MCP in your Cometly dashboard.
- 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), then click Generate Token. - 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 supportstype: http servers with bearer auth. Minimal .mcp.json:
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).
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_workspaceskips 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:space_id argument (a string, the numeric ID from list_my_spaces):
- 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_idthe token’s grant doesn’t cover is refused with an[authorization_error]tool result (HTTP200,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-apiURL, the path names the Space: it must be covered by the token, and a differentspace_idargument 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:
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:- Open Settings → Integrations → MCP in your Cometly dashboard.
- 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), orMCP: Cursor (All spaces)). - Click Revoke.
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.