The MCP server | Convultra Help

What the Convultra MCP server is, the 21 tools, the three prompts, how authentication works, and what to expect once an assistant is connected.

The Convultra MCP server is in Beta. It lives at https://mcp.convultra.com/mcp and lets Claude, ChatGPT, Cursor and your own agents ask questions of your conversion data directly: why conversions dropped last week, which deliveries failed and why, what a campaign actually returned. It exposes the same 21 operations as the REST API, with the same names, the same inputs and the same answers.

What it is

MCP (Model Context Protocol) is the open standard assistants use to call external tools. Convultra’s server is a remote, streamable-HTTP MCP endpoint. It is stateless and accepts POST only; a GET returns 405. There is nothing to install or host: you connect a client to the URL and authenticate.

The 21 tools

Each REST operation is an MCP tool of the same name:

Group	Tools
Identity and health	`get_me`, `get_metric_definitions`, `list_projects`, `get_project`, `get_tracking_health`
Performance	`get_overview`, `get_timeseries`
Traffic sources	`get_breakdown`, `get_ai_referrals`, `get_filtered_out`
Conversions	`list_events`, `get_event_timeseries`, `get_funnel`, `list_conversions`, `get_conversion`, `get_attribution`, `get_recovery`
Delivery	`list_deliveries`, `get_delivery_summary`, `retry_delivery`
Spend	`get_spend`

retry_delivery is the only tool that writes anything. Everything else is read-only. See API operations for what each one returns and the traps.

Prompts and resources

The server also offers three prompts, so an assistant starts from a sensible order of investigation rather than guessing one:

a weekly performance review
diagnosing a conversion drop
triaging delivery failures

And one resource: the metric definitions, the same content as get_metric_definitions, so the assistant can read what a visitor or a conversion rate means before it quotes one.

Authentication

The MCP endpoint accepts both sk_ API keys and OAuth access tokens.

Hosted assistants (Claude.ai, ChatGPT) use OAuth 2.1. They discover the authorization server themselves, the user signs in and approves scopes and projects on a consent screen, and the client receives a cvt_ access token. You never handle the token. See Connect Claude.
Terminal and editor clients (Claude Code, Cursor, your own agent) generally send an sk_ key in an Authorization: Bearer header. See Connect ChatGPT, Cursor and your own agents.

A Claude connector requests the six read scopes an assistant needs: projects:read, analytics:read, conversions:read, delivery:read, spend:read and annotations:read. It asks separately, later, for anything beyond them. See API scopes.

What to expect once it is connected

One question becomes several tool calls. An assistant asked “why did conversions drop last week” will reasonably check tracking health, then the overview, then a breakdown, then delivery: four or five calls for one sentence of question. Your limits are consumed considerably faster than with REST, where you choose each call yourself. On a Starter plan (Basic limits: 60 requests a minute, 5,000 a day) that is a real constraint; get_me tells you what you have. See the rate limit table in the API overview.

Tool results are trimmed for a model. A list comes back with the top 25 rows by default (200 at most) plus a note that more exist, because the interesting rows are at the top and context is expensive. The REST API returns the full page; the MCP tool returns enough to answer. If an assistant tells you it is only seeing part of a list, ask it to narrow the range or filter rather than to fetch more.

Each result carries a plain-language summary alongside the structured data, with the caveats attached: that visitor counts must not be summed across buckets, that only the top ten rows of a dimension exist, that spend is unavailable rather than zero. An assistant that reads only the text still gets an answer it cannot misquote in the obvious ways.

Customer-supplied text stays out of those summaries. Page paths, referrers, UTM values and campaign names appear only in the structured data, never in the prose a model reads first. Anyone can put text into a tracked site’s URL, so the summary is the one surface kept free of it.

Four things to tell your assistant

If you write a system prompt or project instructions for an assistant that uses these tools, these four rules prevent the most common wrong answers:

Call get_tracking_health before concluding anything from a drop. A tracking outage and a bad week look identical in the numbers, and monitoring_mode: true means tracking is fine but nothing is being forwarded.
Conversion rate is conversions divided by visitors, except on breakdown rows where it is per session. Never compare the two.
null is not zero. A null spend or ROAS means the integration is not connected. Report “unavailable”.
AI referrals are humans already in every total; AI crawlers are bots in no total. Never add them to anything.

Rate limits and caching

The same limits and the same response cache apply as on REST. A cache hit does not consume a concurrency slot, and two credentials asking the same question share a hit. Honor Retry-After on a 429.

Errors

Errors have the same codes and shapes as the REST API. On the MCP server, the WWW-Authenticate header on a 401 is what makes an assistant show its “Connect” prompt. See API errors.