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

# Claude Code

> Use the Cometly MCP server from Claude Code (Anthropic's CLI) so your terminal agent can pull live marketing data.

## Prerequisites

* A Cometly workspace and a Space you have **Use Public API** permission in.
* [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed.
* Your numeric **Space ID** — copy it from the **ID** row at the bottom of the dashboard sidebar, or from [**Space Settings**](https://app.cometly.com/space/settings) → **Space Details**. See [Finding your Space ID](/mcp/overview#finding-your-space-id) for step-by-step instructions.

## Add the server

From your terminal:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
claude -p "Using the cometly MCP server, list contacts created this week where Customer Plan is Premium" --output-format=stream-json
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="claude mcp list shows the server but tool calls fail">
    Confirm the URL is correct and that you replaced `{space_id}` with your numeric Space ID. To re-walk OAuth, remove the cached credentials:

    ```bash theme={null}
    rm -rf ~/.claude/mcp/cometly
    ```

    Then ask Claude to use the server again — it'll re-authorize.
  </Accordion>

  <Accordion title="No OAuth URL appears">
    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`.
  </Accordion>

  <Accordion title="403 on subsequent calls after working briefly">
    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.
  </Accordion>
</AccordionGroup>

## Common patterns

* **One-shot analysis in CI:**

  ```bash theme={null}
  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.

  ```bash theme={null}
  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.

  ```bash theme={null}
  claude --allow-tools "mcp:cometly:query_ad_metrics,mcp:cometly:list_events"
  ```