Sumidatasumidata.io
Sign in
Docs/Reference/MCP Server (AI assistant)
Reference · Connect your AI assistant

MCP Server

Connect Claude, Codex or another AI assistant to your Sumidata project and ask about your data in plain language, right where you already work. Your assistant does the thinking; Sumidata gives it read-only access to one project's data and the same metric rules the dashboard uses. The connection uses the Model Context Protocol (MCP).

01What it can do

Read-only answers about one project.

Your assistant can look at sessions, events, orders and revenue, campaigns and ROAS, funnels, experiments, errors, chats, uptime and heatmaps, and combine them in one answer. For example:

  • “What were my top 5 traffic sources last week, and how did they convert?”
  • “Why did checkout conversion drop yesterday?”
  • “Which campaigns paid back their spend this month?”
  • “Which JavaScript errors hit the most paying users?”

It only reads. It cannot change settings, send messages or see billing.

02Connect in three steps

About a minute. No coding.

  1. In the dashboard, open Settings → MCP Server and click Create token.
  2. Pick your assistant and copy the ready-made command or config. The page fills in your token for you and names the server after your project, so several projects can be connected side by side and your assistant knows which one to ask. You can change the name.
  3. Ask your assistant a question about your data.

For reference, this is what the page gives you for a project named Shop, with your token instead of the placeholder:

Run in your terminal
claude mcp add --scope user --transport http sumidata-shop https://api.sumidata.io/mcp --header "Authorization: Bearer <your-token>"

Restart your assistant if it was already open. In Claude Code, type /mcp: sumidata-shop should be listed as connected. Any other client that connects to a remote MCP server over HTTP with a custom header works the same way. Clients that only offer sign-in (OAuth) connections are not supported yet.

03How it works

Your assistant asks, Sumidata answers.

  • When you ask a question, your assistant decides what data it needs and asks Sumidata for it: a ready dashboard report, or a custom query over your analytics.
  • Sumidata answers only for the project the token belongs to and only within your plan's data history.
  • Each data request that completes successfully uses one AI query from your workspace's monthly allowance, the same allowance as AI Analyst. Failed requests, repeats of the same request and status checks are free. Your usage is on the Limits page.

04When a request takes longer than 25 seconds

Long requests keep running after the first 25 seconds.

  • Most answers come back within a few seconds.
  • If a request takes longer than 25 seconds, your assistant is told the work is still running. Sumidata keeps working on it for up to 2 minutes.
  • Your assistant normally checks back on its own after about a minute and picks up the result. If it doesn't, ask it to “check the result of the running operation”.
  • A finished result is kept for 1 hour. Checking it again does not run the work again and does not use another AI query.
  • If the work takes longer than 2 minutes, it is stopped and no AI query is charged. Ask a narrower question, for example a shorter period.

05Limits and response codes

What the server returns when a limit is reached.

SituationServer response
Too many requests: over 60 per minute per workspace (short bursts up to 20), over 120 per minute from one address (bursts up to 30), or the platform-wide limitHTTP 429 with a Retry-After header in seconds
Two data requests are already running for your workspace, or the service is busyHTTP 200, tool error overloaded with retryAfterSeconds
The monthly AI-query allowance is used upHTTP 200, tool error quota_exceeded with resetsAt (the reset date)
The work ran longer than 2 minutesTool error timeout
The result is too large to returnTool error result_too_large
Missing, wrong or revoked tokenHTTP 401
Request sent from a web page in a browserHTTP 403
Request body over 64 KBHTTP 413
i
Why HTTP 200 for some limits? In MCP, a refused tool call is reported inside a normal response as a tool error, so your assistant can read the reason and decide what to do: wait and retry, or tell you the allowance is used up. Assistants that use MCP background tasks receive the same refusals as a JSON-RPC error carrying the same kind.

06Security

What the token can and cannot do.

  • A token reads one project only, with the access of a regular team member. Billing is never available.
  • Nothing is changed: reading a chat does not even mark it as read.
  • Revoke the token on the API Tokens page and access stops on the next request. Removing the person who created it from the team does not revoke it.