> ## 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 gets a single MCP endpoint:
```
https://app.cometly.com/mcp/{space_id}/public-api
```
Replace `{space_id}` with the numeric ID of the Space you want the client to talk to. See [Finding your Space ID](#finding-your-space-id) below.
## Finding your Space ID
Every MCP URL embeds a numeric Space ID. You'll need it when configuring Cursor, Claude Desktop, ChatGPT, or any other client.
**From the dashboard sidebar (fastest)** — In the Cometly app, look at the **bottom of the left navigation menu**. Under the **Support** heading (above Help Center), you'll see a compact **ID** row with your current Space's numeric ID and a **copy** icon. Click the icon to copy the ID, then paste it into your MCP endpoint URL.
**From Space Settings** — Open [**Space Settings**](https://app.cometly.com/space/settings). Scroll to the **Space Details** section at the bottom of the page and find **Space ID** — click the copy icon next to the number.
You can also reach that page from the dashboard: go to **Setup → Additional Setup → Manage Space Settings**.
The ID is just the number (for example, `6116`). Plug it into the endpoint above:
```
https://app.cometly.com/mcp/6116/public-api
```
## What you can do
The server exposes **50 read-only tools** across 14 toolsets — workspace orientation, search, analytics, events, contacts, companies, ads-manager hierarchy, reports, segments, 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.
All 50 tools are **read-only**. There are no write tools — no way for an MCP client to create, modify, or delete data in your workspace.
Call [`get_workspace_context`](/mcp/tools/get-workspace-context) once at session start (or subscribe to the `cometly://workspace/context` [Resource](/mcp/resources/overview)) 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`](/mcp/tools/get-workspace-context), [`list_custom_events`](/mcp/tools/list-custom-events), [`resolve_date_range`](/mcp/tools/resolve-date-range) |
| **Search** | [`search_workspace`](/mcp/tools/search-workspace) — fuzzy lookup across campaigns, ads, contacts, reports, and more |
| **Analytics** | [`query_ad_metrics`](/mcp/tools/query-ad-metrics), [`query_ad_metrics_compare`](/mcp/tools/query-ad-metrics-compare), [`query_attribution_models`](/mcp/tools/query-attribution-models), [`query_metric_breakdown`](/mcp/tools/query-metric-breakdown) |
| **Events** | [`list_events`](/mcp/tools/list-events), [`query_events_aggregated`](/mcp/tools/query-events-aggregated), [`list_event_types`](/mcp/tools/list-event-types) |
| **Contacts & Companies** | List/detail/journey tools plus [`query_contacts_aggregated`](/mcp/tools/query-contacts-aggregated) |
| **Ads Manager** | [`list_ad_accounts`](/mcp/tools/list-ad-accounts) through [`get_ad_entity`](/mcp/tools/get-ad-entity) |
| **Reports** | Dashboards, saved reports, [`run_saved_report`](/mcp/tools/run-saved-report), [`analyze_report`](/mcp/tools/analyze-report) (deducts AI credits) |
| **Segments** | [`list_segments`](/mcp/tools/list-segments), [`query_segment_membership`](/mcp/tools/query-segment-membership) |
| **Integrations** | [`get_pixel_status`](/mcp/tools/get-pixel-status), [`list_event_mappings`](/mcp/tools/list-event-mappings) |
| **Health & Diagnostics** | [`get_space_health`](/mcp/tools/get-space-health), [`debug_data_flow`](/mcp/tools/debug-data-flow), [`inspect_site`](/mcp/tools/inspect-site), [`verify_pixel_events`](/mcp/tools/verify-pixel-events) |
| **Webhooks** | [`list_recent_webhooks`](/mcp/tools/list-recent-webhooks), [`get_webhook_event`](/mcp/tools/get-webhook-event) — payloads PII-redacted |
| **AI helpers** | [`search_cometly_docs`](/mcp/tools/search-cometly-docs), [`get_chart_spec_template`](/mcp/tools/get-chart-spec-template) |
See the full catalog with parameters and examples in the [Tools Reference](/mcp/tools/overview).
### Resources & Prompts
Beyond tools, the server exposes:
* **5 Resources** — subscribable reference data (`cometly://catalog/metrics`, `cometly://catalog/custom-events`, etc.). See [Resources](/mcp/resources/overview).
* **4 Prompts** — reusable slash-command templates like `weekly_review` and `analyze_performance`. See [Prompts](/mcp/prompts/overview).
### 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](/api-reference/endpoint/create-event-export) or the in-app CSV export buttons instead of routing rows through an LLM turn.
## How it's secured
Connections use OAuth 2.1 with PKCE. Clients identify themselves via a hosted metadata document (CIMD — the preferred path for new clients) or Dynamic Client Registration (RFC 7591). The first time an MCP-aware client hits 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 dynamically and opens the Cometly authorization page in your browser.
3. You log in, pick which Space the client is allowed to access, and click **Approve**.
4. The client exchanges the resulting authorization code for an access token bound to that Space.
Subsequent tool calls carry that token as a bearer credential. The token is a Sanctum personal access token with a single `mcp_space:{id}` ability — it can only act on the Space you approved, and your Space-membership and permission checks run on every request, so revoking a user from a Space immediately revokes their MCP access without any token cleanup.
See [Authentication](/mcp/authentication) for the full flow.
## 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`](/mcp/tools/list-contacts) and [`list_events`](/mcp/tools/list-events) for the `custom_field_filters` parameter.
## Where to next
The OAuth 2.1 flow, scopes, and how to manage connected clients.
Install Cometly as an MCP server in Cursor in 30 seconds.
Install in Claude Desktop's MCP settings.
Every tool, every parameter, every operator.
Subscribable metric catalogs, dimension lists, and workspace context.
One-click analysis templates like weekly reviews and attribution comparisons.