> ## 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 are a member of.
* [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed.

## Add the server

From your terminal:

```bash theme={null}
claude mcp add --transport http cometly https://app.cometly.com/mcp
```

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:

```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, 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:

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

> [accordion] claude mcp list shows the server but tool calls fail
>
> 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:
>
> ```bash theme={null}
> claude mcp remove cometly
> claude mcp add --transport http cometly https://app.cometly.com/mcp
> ```

> [accordion] 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] Calls start failing with an authorization error after working briefly
>
> 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:**

  ```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 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`](https://docs.cometly.com/mcp/tools/list-my-spaces).

  ```bash theme={null}
  claude mcp add --transport http cometly https://app.cometly.com/mcp
  ```

  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.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.