Skip to main content

Prerequisites

  • A Cometly workspace and a Space you are a member of.
  • Claude Code installed.

Add the server

From your terminal:
Claude Code stores the server in ~/.claude.json (the default local scope; add --scope user to make it available in every project). To inspect what was saved:

Authorize

The first time Claude Code uses the server, it’ll print an OAuth URL to your terminal. Open it in your browser, log in, choose which Spaces to grant (all of yours or specific ones, with a default), and click Approve. Claude Code completes the handshake and keeps the token for you; /mcp shows the connection state.

Verify

Start a new session and ask:
You should see a query_ad_metrics tool call followed by a real answer. If you’d rather invoke the server programmatically (e.g. from a CI job), you can pipe a prompt straight in:

Troubleshooting

Confirm the URL is https://app.cometly.com/mcp. To re-walk OAuth, run /mcp, select cometly and choose Clear authentication, then ask Claude to use the server again. If the server itself is misconfigured, remove and re-add it:
Make sure you’re on a recent Claude Code version that supports HTTP transport MCP servers. claude --version should be at least the version that ships with claude mcp add --transport http.
You’re calling an older /mcp/{space_id}/public-api URL and the token was approved for a different Space, or you’re no longer a member of the Space. Switch to https://app.cometly.com/mcp, remove the credentials, and re-authorize, including the correct Space.

Common patterns

  • One-shot analysis in CI:
  • Interactive across Spaces: add the server once and choose All my spaces (or the Spaces you need) on the consent screen. Claude runs in your default Space unless you name another one, and passes its space_id from list_my_spaces.
    Then prompt with the Space name: “In the Beta Co. Space, …”
  • Scoped tool restriction: Claude Code respects per-server --allow-tools flags if you want to limit a session to just read-only metric queries.