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.
What MCP is
The Model Context Protocol 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.”
The endpoint
Every Cometly Space gets a single MCP endpoint:{space_id} with the numeric ID of the Space you want the client to talk to. See 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. 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:
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.Toolsets at a glance
| Toolset | Highlights |
|---|---|
| Workspace | get_workspace_context, list_custom_events, resolve_date_range |
| Search | search_workspace — fuzzy lookup across campaigns, ads, contacts, reports, and more |
| Analytics | query_ad_metrics, query_ad_metrics_compare, query_attribution_models, query_metric_breakdown |
| Events | list_events, query_events_aggregated, list_event_types |
| Contacts & Companies | List/detail/journey tools plus query_contacts_aggregated |
| Ads Manager | list_ad_accounts through get_ad_entity |
| Reports | Dashboards, saved reports, run_saved_report, analyze_report (deducts AI credits) |
| Segments | list_segments, query_segment_membership |
| Integrations | get_pixel_status, list_event_mappings |
| Health & Diagnostics | get_space_health, debug_data_flow, inspect_site, verify_pixel_events |
| Webhooks | list_recent_webhooks, get_webhook_event — payloads PII-redacted |
| AI helpers | search_cometly_docs, get_chart_spec_template |
Resources & Prompts
Beyond tools, the server exposes:- 5 Resources — subscribable reference data (
cometly://catalog/metrics,cometly://catalog/custom-events, etc.). See Resources. - 4 Prompts — reusable slash-command templates like
weekly_reviewandanalyze_performance. See Prompts.
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 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 and Dynamic Client Registration (RFC 7591). The first time an MCP-aware client hits the endpoint:- The client gets back a
401 Unauthorizedwith aWWW-Authenticateheader pointing at the OAuth discovery URL. - The client registers itself dynamically and opens the Cometly authorization page in your browser.
- You log in, pick which Space the client is allowed to access, and click Approve.
- The client exchanges the resulting authorization code for an access token bound to that Space.
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 for the full flow.
Audit log
Every tool call is recorded in an immutablemcp_audit_log row with:
correlation_id— surfaced in error envelopes so support can trace failurestool_name,args(digest only, no PII),latency_ms,output_size_bytesspace_id,user_id,token_id,client_user_agent,client_ipwas_internalflag to distinguish external MCP clients from in-app Ask AI
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 and list_events for the custom_field_filters parameter.
Where to next
Authentication
The OAuth 2.1 flow, scopes, and how to manage connected clients.
Connect Cursor
Install Cometly as an MCP server in Cursor in 30 seconds.
Connect Claude Desktop
Install in Claude Desktop’s MCP settings.
Tools Reference
Every tool, every parameter, every operator.
Resources
Subscribable metric catalogs, dimension lists, and workspace context.
Prompts
One-click analysis templates like weekly reviews and attribution comparisons.