Asking from your own assistant

AI explains. TraceLog computes.

Connect your assistant to query one project's data. The key is read-only and respects your plan's limits. Each result includes a link to rerun the query in TraceLog's explorer.

Your assistant chooses the query, and every number comes from TraceLog running it. TraceLog receives only the query your assistant composes, never what you typed.

What the key can and cannot do

An assistant key is read-only and scoped to one project. It can run these queries and nothing else.

• It reads what a member of that project can already read in the explorer, and nothing more. Your tier and your account's standing apply to it exactly as they apply to the explorer.
• It writes nothing. It cannot send an event, change your tracking plan, read your members, or reach another project.
• It is not a role. Nothing it does is attributed to a person, and it carries no session.

Create it in Project settings → Channels & credentials → Create assistant key. The value is shown once, at creation, and cannot be shown again — copy it then. Revoke it there too; a revoked key stops working immediately. There is no rotation: to replace a key, create a new one and revoke the old one.

The key looks like this:

Authorization: Bearer tl_ak_xxxxxxxxxxxxxxxxxxxxxxxxxx

It sits in plain text in the configuration file you paste it into. That file is on your machine, not TraceLog's. Treat it the way you treat any other credential in a dotfile: do not commit it, and revoke it if the machine is lost.

The endpoint

It speaks the Model Context Protocol over HTTP, POST only. There is no event stream and no session to open: one request carries one answer.

Claude Code

One command, from the directory you want it available in:

claude mcp add --transport http tracelog https://api.tracelog.io/v1/assistant/mcp \
  --header "Authorization: Bearer tl_ak_xxxxxxxxxxxxxxxxxxxxxxxxxx"

Cursor

In .cursor/mcp.json:

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

Claude Desktop

Claude Desktop launches its servers as local processes, so it reaches an HTTP endpoint through mcp-remote. In claude_desktop_config.json:

{
  "mcpServers": {
    "tracelog": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@0.1.38",
        "https://api.tracelog.io/v1/assistant/mcp",
        "--header",
        "Authorization: Bearer tl_ak_xxxxxxxxxxxxxxxxxxxxxxxxxx",
        "--transport",
        "http-only"
      ]
    }
  }
}

The version of mcp-remote is pinned, so it changes only when you change it.

The one tool

The server has one tool, run_semantic_query. Each query asks for one metric, sessions, events, conversions, conversion_rate or step_rate, over a period of calendar days in your project's timezone. It can also:

• break the result down by one dimension of the session's origin;
• filter every figure to one value of one dimension, other than the one it breaks down by;
• compare the period with another one;
• return the period week by week, Monday to Sunday, over at most 371 days. A weekly series has no breakdown and no comparison.

The tool's description names the conversions and steps your tracking plan declares, so your assistant does not have to guess what exists.

Every answer comes back with an explorer link. Open it and the explorer runs the same query and shows the same numbers.

How a limit is explained

A limit is returned as an answer, not an error. The result names the reason and explains it, so your assistant can tell you what happened.

Ask a free-tier project to cut or filter sessions by channel, and this comes back:

{
  "refused": "paid_dimension",
  "sentence": "Channel, campaign, term, AI origin, device, country and landing page are included in Pro. Your data already supports them; on Free they stay closed."
}

Your data is still recorded on your current plan; only access to that view is limited. Capture, alerts and the funnel do not change.

The other limits are explained in the same way:

• a project that is not verified yet has no conversion figures until its declared path is verified;
• an element your plan does not declare was never expected to arrive;
• a paused account is told which action resumes it;
• a free project asking about more than its last 30 days, or comparing with another period, is told that this is included in Pro.

Capture of the declared path never stops because of a plan limit.

Web connectors

The connectors that live inside claude.ai and ChatGPT require OAuth, and this endpoint authenticates with a key. They are not supported yet; the three clients above are.