Skip to main content

​
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.”
…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:
Replace {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.
Call get_workspace_context once at session start (or subscribe to the cometly://workspace/context Resource) so the model knows your timezone, currency, connected ad accounts, and custom event labels before it starts querying.

​
Toolsets at a glance

See the full catalog with parameters and examples in the Tools Reference.

​
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_review and analyze_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 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, 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 scoped with mcp_space:{id}, so it can only act on the Space you approved, and your Space membership and permissions are checked on every request. Removing a user from a Space immediately revokes their MCP access, 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 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 and list_events for the custom_field_filters parameter.

​
Where to next

Authentication

OAuth 2.1 for browser-based clients, personal access tokens for server-side agents, scopes, and revoking access.

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.