MCP Server

TraceLog exposes a read-only subset of its analyst tools over the Model Context Protocol, so you can ask about your store's data from wherever you already work — Claude Desktop, an IDE assistant, or your own agent — instead of opening the dashboard.

Limited availability

The MCP server is in a limited internal phase and is not open to all accounts yet. If you'd like early access, get in touch. Everything below is the contract it will ship with.

What it can and cannot do

It reads. Nothing exposed here changes anything in your project — there is no tool to edit, dismiss, resolve, or delete. The one Ask tool that writes is deliberately excluded.

Six tools are available:

Tool	Required arguments	Returns
`list_projects`	—	Your projects, with id, name, currency, and whether revenue tracking is configured
`describe_available_data`	`project_id`	What this project actually holds: metrics, dimensions, custom events, funnels, tracking start date
`query_metrics`	`project_id`, `startDate`, `endDate`	Sessions, visitors, page views, bounce rate, average duration, engagement rate, errors
`get_traffic_breakdown`	`project_id`, `dimension`	Traffic ranked by one dimension (referrer, utm_source, country, device, landing page, …)
`search_issues`	`project_id`, `query`	Issues TraceLog detected — errors, page problems, tracking gaps
`get_top_loss`	`project_id`	The highest-ranked loss currently in the Attention queue, with money impact and recommended action

Call list_projects first. Every other tool needs a project_id, and none of them will guess one.

Connecting

Endpoint

POST https://api.tracelog.io/mcp
Authorization: Bearer <YOUR_MCP_TOKEN>

It speaks JSON-RPC over the MCP Streamable HTTP transport, and it is stateless — every request carries its own token and its own project_id, so there is no session to expire and no chance of answering about the wrong project after a reconnect.

Getting a token

Generate one from the MCP section of the dashboard. The token is shown once — copy it then, because it is stored only as a hash and cannot be recovered. If you lose it, revoke it and generate another.

A few things worth knowing about the credential:

It is scoped to you, not to a project. One token reads every project you have access to; access is re-checked on every single call, so removing your access to a project takes effect immediately.
It is not your project's ingest API key, and the two are not interchangeable. The ingest key can write events; this one cannot do anything but read. Keep them separate — MCP config tends to end up in dotfiles and pasted messages.
Revoke it any time from the same screen. A revoked token stops working immediately.

Client configuration

Clients that support remote MCP servers over HTTP take the URL and the header directly:

{
  "mcpServers": {
    "tracelog": {
      "url": "https://api.tracelog.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

Clients that only speak stdio need a bridge such as mcp-remote in front of the same URL. Check your client's own documentation for the exact file and field names — they differ between clients.

Reading the answers

Every response is wrapped in an envelope that carries the qualification the numbers need. This matters more here than in the dashboard: the model reading your data has none of TraceLog's context, so anything the payload does not state, it will fill in from its own assumptions — confidently, in your assistant's voice.

{
  "tool": "query_metrics",
  "project": { "id": "…", "name": "Your Store" },
  "period": { "start": "2026-07-01T00:00:00.000Z", "end": "2026-07-31T23:59:59.999Z", "timezone": "UTC" },
  "currency": "EUR",
  "sample": { "sessions": 65710, "floor": 10, "sufficient": true },
  "guidance": "Rates rest on the session count in `sample`. …",
  "data": { "sessions": 65710, "bounceRate": "41.2%", "…": "…" }
}

period is the window the query actually ran on, always UTC — not a description of it. Read it instead of assuming what "last month" meant.
currency is your store's trading currency, and appears only on tools that return money. It is never defaulted, so if it is absent the figure is not in euros or dollars — it is unlabelled, and should be reported that way.
sample is the session count the answer rests on, and floor is the minimum needed for a rate to mean anything.
guidance names the specific over-reach that tool invites. It is worth reading before summarising.

When a metric is missing

Below the sample floor, rate metrics are removed from data and listed in suppressed:

{
  "sample": { "sessions": 4, "floor": 10, "sufficient": false },
  "suppressed": [
    { "field": "bounceRate", "reason": "Sample of 4 sessions is below the 10-session floor this metric requires." }
  ],
  "data": { "sessions": 4, "visitors": 3, "pageViews": 7 }
}

This is deliberate. A bounce rate of 0 is an assertion, and a reading model will happily pass it on as "your bounce rate is 0%". An absent field cannot be turned into a claim. Treat a suppressed metric as "not measurable", never as zero, and do not recompute it from the other fields.

Date windows

For tools that take dates:

Supply both startDate/endDate or neither. Half a window is refused rather than quietly completed.
Use unambiguous ISO 8601 (YYYY-MM-DD). Formats like 02/01/2026 mean different days in different places and are refused rather than guessed.
The window must run forwards, end no later than today, and span at most 365 days.
Omit both and the server applies a 30-day window, then reports it back in period.

A window outside those bounds is refused with an error explaining why, rather than silently narrowed to something you did not ask for.

Limits

Rate limit: 120 calls per minute per token. An agent that loops can fire dozens of calls per question, and each one is a real query against your data.
Plan allowance: every project-scoped tool call spends one AI query from your plan's monthly allowance — the same allowance Ask uses, because these are the same queries. list_projects is free. A call that fails or returns no data does not spend anything.

See Plans for your allowance, and Ask for the same tools inside the dashboard.

What it can and cannot do​

Connecting​

Reading the answers​

When a metric is missing​

Date windows​

Limits​