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

# MCP Overview

> Connect Claude Desktop, Cursor, and any MCP-aware client to your Cometly workspace and let it query your marketing analytics in natural language.

## What MCP is

The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard that lets AI clients (Claude Desktop, Cursor, Claude Code, ChatGPT's Desktop app, your own custom agents) discover and call tools on a remote server. Cometly exposes its analytics data as an MCP server so you can ask your AI tools things like:

* *"What was my ROAS by source last month?"*
* *"List contacts created this week where Customer Plan is Premium."*
* *"Compare CPA across Meta and Google for the last 30 days vs the prior 30 days."*

…and the model will pick the right tool, call it against your workspace's live data, and answer in plain English with charts and tables.

## The endpoint

Every Cometly Space is reached through one fixed MCP endpoint:

```
https://app.cometly.com/mcp
```

The Space isn't part of the URL. The first time a client connects, you choose what the connection may use on the Cometly consent screen: one Space, specific Spaces, or **All my spaces** (every Space you belong to, including ones you're added to later), plus a **default Space**. Every tool takes an optional `space_id` to run in another Space the connection covers, and runs in the default Space without it. Call [`list_my_spaces`](https://docs.cometly.com/mcp/tools/list-my-spaces) to see which Spaces a connection can use.

ChatGPT is the one exception: give it `https://app.cometly.com/mcp/chatgpt`, the same server on a path that lets ChatGPT read the tool list before you link your account (see [ChatGPT](https://docs.cometly.com/mcp/connecting/chatgpt.md)).

> [!NOTE]
>
> Connections made before MCP v2.6.0 use the older per-Space URL, `https://app.cometly.com/mcp/{space_id}/public-api`. It still works as an alias, so existing connections and configs need no change. For anything new, use `https://app.cometly.com/mcp`.

## What you can do

The server exposes **50+ tools** across 13 toolsets — workspace orientation, search, analytics, events, contacts, companies, ads-manager hierarchy, reports, integrations, health, diagnostics, webhooks, and AI helpers. Most tools wrap the same engines that power Cometly's report builder, Public API V1, and in-app dashboards; a handful (saved reports, webhook debugging, site inspection) are MCP-native.

Nearly every tool is **read-only**. Three write tools exist — `update_contact`, `update_company`, and [`update_event`](https://docs.cometly.com/mcp/tools/update-event) — and each one edits fields on a single record you address by ID. No tool can create or delete data in your workspace, and none can change attribution. [Read-only tokens](https://docs.cometly.com/mcp/authentication.md#read-only-tokens) hide even those three, and so do connections made by Viewers (members whose role has no permissions), whose connections also leave out the contact and company tools, the data the app hides from that role.

> [!TIP]
>
> Call [`get_workspace_context`](https://docs.cometly.com/mcp/tools/get-workspace-context) once at session start (or subscribe to the `cometly://workspace/context` [Resource](https://docs.cometly.com/mcp/resources/overview.md)) so the model knows your timezone, currency, connected ad accounts, and custom event labels before it starts querying.

### Toolsets at a glance

| Toolset | Highlights |
| - | - |
| **Workspace** | [`get_workspace_context`](https://docs.cometly.com/mcp/tools/get-workspace-context), [`list_custom_events`](https://docs.cometly.com/mcp/tools/list-custom-events), [`resolve_date_range`](https://docs.cometly.com/mcp/tools/resolve-date-range) |
| **Search** | [`search_workspace`](https://docs.cometly.com/mcp/tools/search-workspace) — fuzzy lookup across campaigns, ads, contacts, reports, and more |
| **Analytics** | [`query_ad_metrics`](https://docs.cometly.com/mcp/tools/query-ad-metrics), [`query_ad_metrics_compare`](https://docs.cometly.com/mcp/tools/query-ad-metrics-compare), [`query_attribution_models`](https://docs.cometly.com/mcp/tools/query-attribution-models), [`query_metric_breakdown`](https://docs.cometly.com/mcp/tools/query-metric-breakdown) |
| **Events** | [`list_events`](https://docs.cometly.com/mcp/tools/list-events), [`query_events_aggregated`](https://docs.cometly.com/mcp/tools/query-events-aggregated), [`list_event_types`](https://docs.cometly.com/mcp/tools/list-event-types), [`update_event`](https://docs.cometly.com/mcp/tools/update-event) (write) |
| **Contacts & Companies** | List/detail/journey tools plus [`query_contacts_aggregated`](https://docs.cometly.com/mcp/tools/query-contacts-aggregated) |
| **Ads Manager** | [`list_ad_accounts`](https://docs.cometly.com/mcp/tools/list-ad-accounts) through [`get_ad_entity`](https://docs.cometly.com/mcp/tools/get-ad-entity) |
| **Reports** | Dashboards, saved reports, [`run_saved_report`](https://docs.cometly.com/mcp/tools/run-saved-report), [`analyze_report`](https://docs.cometly.com/mcp/tools/analyze-report) (deducts AI credits) |
| **Integrations** | [`get_pixel_status`](https://docs.cometly.com/mcp/tools/get-pixel-status), [`list_event_mappings`](https://docs.cometly.com/mcp/tools/list-event-mappings) |
| **Health & Diagnostics** | [`get_space_health`](https://docs.cometly.com/mcp/tools/get-space-health), [`debug_data_flow`](https://docs.cometly.com/mcp/tools/debug-data-flow), [`inspect_site`](https://docs.cometly.com/mcp/tools/inspect-site), [`verify_pixel_events`](https://docs.cometly.com/mcp/tools/verify-pixel-events) |
| **Webhooks** | [`list_recent_webhooks`](https://docs.cometly.com/mcp/tools/list-recent-webhooks), [`get_webhook_event`](https://docs.cometly.com/mcp/tools/get-webhook-event) — payloads PII-redacted |
| **AI helpers** | [`search_cometly_docs`](https://docs.cometly.com/mcp/tools/search-cometly-docs), [`get_chart_spec_template`](https://docs.cometly.com/mcp/tools/get-chart-spec-template) |

See the full catalog with parameters and examples in the [Tools Reference](https://docs.cometly.com/mcp/tools/overview.md).

### Resources & Prompts

Beyond tools, the server exposes:

* **5 Resources** — subscribable reference data (`cometly://catalog/metrics`, `cometly://catalog/custom-events`, etc.). See [Resources](https://docs.cometly.com/mcp/resources/overview.md).
* **4 Prompts** — reusable slash-command templates like `weekly_review` and `analyze_performance`. See [Prompts](https://docs.cometly.com/mcp/prompts/overview.md).

### Bulk extraction

The MCP is for *analysis*, not bulk file export. As of **v2.1.0**, the four export tools (`request_event_export`, `request_contact_export`, `request_company_export`, `get_export_status`) were removed. For large datasets, use the [Public API V1 export endpoints](https://docs.cometly.com/api-reference/endpoint/create-event-export.md) or the in-app CSV export buttons instead of routing rows through an LLM turn.

## How it's secured

Connections use either **OAuth 2.1 with PKCE** (browser-based clients) or a **personal access token** (server-side agents). MCP-aware clients like Claude Desktop and Cursor use OAuth automatically. The first time they hit the endpoint:

1. The client gets back a `401 Unauthorized` with a `WWW-Authenticate` header pointing at the OAuth discovery URL.
2. The client registers itself (via CIMD or Dynamic Client Registration) and opens the Cometly authorization page in your browser.
3. You log in, choose which Spaces the client may access (one, specific ones, or all of yours) and a default Space, and click **Approve**. Viewers are told the connection will be read-only.
4. The client exchanges the resulting authorization code for an access token covering those Spaces.

Subsequent tool calls carry that token as a bearer credential. The token's `mcp_space:` ability lists the Spaces you approved, so it can only act on those, and your Space membership and role in the target Space are checked on every request. Every member of a Space can connect, not only Administrators. Viewers get a read-only connection, and your role is re-checked on every write call, so a member demoted to Viewer loses the write tools immediately. Removing a user from a Space immediately cuts off their MCP access to it, with no token cleanup needed.

For **headless use cases** (CI jobs, scripts, backend services) where there's no browser, you can generate a personal access token from **Settings → Integrations → MCP** and send it as a bearer header directly, with no OAuth flow required.

See [Authentication](https://docs.cometly.com/mcp/authentication.md) for the full flow, including how to generate a token and the token limits.

## Audit log

Every tool call is recorded in an immutable `mcp_audit_log` row with:

* `correlation_id` — surfaced in error envelopes so support can trace failures
* `tool_name`, `args` (digest only, no PII), `latency_ms`, `output_size_bytes`
* `space_id`, `user_id`, `token_id`, `client_user_agent`, `client_ip`
* `was_internal` flag to distinguish external MCP clients from in-app Ask AI

Auditing is on by default for every workspace — no setup needed.

## Custom fields

Tools that touch profile data — `list_contacts`, `get_contact`, `list_events`, `query_ad_metrics` — automatically inject your Space's configured custom field labels into their input schema descriptions, so the model sees `profile_field_5 — "Customer Plan" (text)` instead of just `profile_field_5`. You can also **filter** by custom field values directly: see [`list_contacts`](https://docs.cometly.com/mcp/tools/list-contacts) and [`list_events`](https://docs.cometly.com/mcp/tools/list-events) for the `custom_field_filters` parameter.

## Where to next

> [card] [Authentication](https://docs.cometly.com/mcp/authentication.md)
>
> OAuth 2.1 for browser-based clients, personal access tokens for server-side agents, scopes, and revoking access.

> [card] [Connect Cursor](https://docs.cometly.com/mcp/connecting/cursor.md)
>
> Install Cometly as an MCP server in Cursor in 30 seconds.

> [card] [Connect Claude Desktop](https://docs.cometly.com/mcp/connecting/claude-desktop.md)
>
> Install in Claude Desktop's MCP settings.

> [card] [Tools Reference](https://docs.cometly.com/mcp/tools/overview.md)
>
> Every tool, every parameter, every operator.

> [card] [Resources](https://docs.cometly.com/mcp/resources/overview.md)
>
> Subscribable metric catalogs, dimension lists, and workspace context.

> [card] [Prompts](https://docs.cometly.com/mcp/prompts/overview.md)
>
> One-click analysis templates like weekly reviews and attribution comparisons.


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