Authentication

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 Unauthorized with a WWW-Authenticate header 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, pick which Space to grant access to, and click Approve.
The client exchanges the resulting code for an access token bound to that Space.

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 (preferred — no registration call required) and Dynamic Client Registration (fallback, e.g. for custom URI schemes). If you want the gritty detail, keep reading.

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/{space_id}/public-api`

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.

Discovery metadata

Hitting the auth-server metadata endpoint returns:

{
  "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"],
  "client_id_metadata_document_supported": true
}

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 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.

{
  "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 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:

{
  "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 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 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. (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 10 registrations per hour per IP. Legitimate clients register once per install, so this leaves plenty of headroom for retries 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.

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

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

The user logs in (if not already), then picks the Space and clicks Approve.
Cometly redirects back to your redirect_uri with ?code={code}&state={state}.

Exchange the code:

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:

{
  "access_token": "1|abc...",
  "token_type": "Bearer",
  "expires_in": null,
  "scope": "mcp_space:42"
}

Calling the MCP server

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

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

The Space ID in the URL must match the Space the token was approved for — Cometly checks the token’s mcp_space:{id} ability against the route param on every request and returns 403 if they disagree.

Scopes

There’s a single MCP scope today:

Scope	What it grants
`mcp_space:{id}`	Call any read-only tool against Space `{id}`. The Space ID is bound into the scope string — a token approved for Space 42 cannot read Space 43.

When you click Approve in the consent UI, the token’s ability is set to exactly one mcp_space:{id} value. There’s no broader “all spaces” scope, by design.

Revoking access

You can revoke a connected MCP client at any time:

Open Settings → API Tokens in your Cometly dashboard.
Find the token whose name matches the MCP client (e.g. MCP — Claude Desktop).
Click Revoke.

The next tool call from that client gets 401 Unauthorized and the client will walk the auth flow again on next launch (or you can just remove it from the client’s MCP settings). Removing a user from a Space also immediately revokes any MCP tokens they have for that Space — there’s no separate cleanup step.

Common errors

Status	Meaning	Recovery
`401`	No / invalid / expired token.	Walk the OAuth flow again. The `WWW-Authenticate` header includes the discovery URL.
`403`	Token’s `mcp_space:{id}` doesn’t match the URL’s Space ID, or the user no longer has API permission in that Space.	Re-authorize with the correct Space.
`403` (subscription)	The Space’s team doesn’t have an active Public API subscription.	Reach out to your Cometly admin or contact sales.
`429`	Rate limit exceeded.	Back off. See Rate Limits & Errors.

Get Started

Connecting Clients

Tools

Resources

Prompts

TL;DR

Endpoints

Discovery metadata

Client ID Metadata Document (CIMD)

Metadata document

Accepted `redirect_uris` for CIMD clients

Document fetching and caching

Dynamic client registration

Accepted `redirect_uris`

Default allowed https hosts

Accepted `client_name`

Rate limits

Authorization flow

Calling the MCP server

Scopes

Revoking access

Common errors

​TL;DR

​Endpoints

​Discovery metadata

​Client ID Metadata Document (CIMD)

​Metadata document

​Accepted redirect_uris for CIMD clients

​Document fetching and caching

​Dynamic client registration

​Accepted redirect_uris

​Default allowed https hosts

​Accepted client_name

​Rate limits

​Authorization flow

​Calling the MCP server

​Scopes

​Revoking access

​Common errors

TL;DR

Endpoints

Discovery metadata

Client ID Metadata Document (CIMD)

Metadata document

Accepted `redirect_uris` for CIMD clients

Document fetching and caching

Dynamic client registration

Accepted `redirect_uris`

Default allowed https hosts

Accepted `client_name`

Rate limits

Authorization flow

Calling the MCP server

Scopes

Revoking access

Common errors