Skip to main content

​
Prerequisites

  • A Cometly workspace and a Space you have Use Public API permission in.
  • Claude Code installed.
  • Your numeric Space ID — copy it from the ID row at the bottom of the dashboard sidebar, or from Space Settings → Space Details. See Finding your Space ID for step-by-step instructions.

​
Add the server

From your terminal:
Replace 42 with your Space ID. Claude Code stores the config in ~/.claude/config.json. 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, pick the Space, and click Approve. Claude Code completes the handshake and caches the token at ~/.claude/mcp/cometly/credentials.json.

​
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 correct and that you replaced {space_id} with your numeric Space ID. To re-walk OAuth, remove the cached credentials:
Then ask Claude to use the server again — it’ll re-authorize.
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.
The token was approved for a different Space than the one in the URL, or you lost API permission. Remove the credentials and re-authorize, picking the correct Space.

​
Common patterns

  • One-shot analysis in CI:
  • Interactive with explicit Space switching: add multiple servers under different names if you regularly work across spaces.
    Then prompt with the explicit name: “Using cometly-prod, …”
  • Scoped tool restriction: Claude Code respects per-server --allow-tools flags if you want to limit a session to just read-only metric queries.