Skip to main content

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.

​
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: 
claude mcp add --transport http cometly https://app.cometly.com/mcp/42/public-api
Replace 42 with your Space ID. Claude Code stores the config in ~/.claude/config.json. To inspect what was saved: 
claude mcp list

​
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: 
claude

> Using the cometly MCP server, show me my ROAS by source for the last 30 days.
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: 
claude -p "Using the cometly MCP server, list contacts created this week where Customer Plan is Premium" --output-format=stream-json

​
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:
rm -rf ~/.claude/mcp/cometly
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: 
    claude -p "Use the cometly server to pull yesterday's purchase volume by source and write the summary to ./reports/$(date -I).md"
  • Interactive with explicit Space switching: add multiple servers under different names if you regularly work across spaces. 
    claude mcp add --transport http cometly-prod https://app.cometly.com/mcp/42/public-api
claude mcp add --transport http cometly-staging https://app.cometly.com/mcp/99/public-api
    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. 
    claude --allow-tools "mcp:cometly:query_ad_metrics,mcp:cometly:list_events"