MCP server

This page shows how to connect an AI agent to your workspace, so you can ask it "which pages lost the most visitors this week?" and let it read the answer from your own numbers. MCP, the Model Context Protocol, is the common way for an agent to use the tools of another product.

The address and the token #

The server has one address:

https://clearsaga.com/mcp

It is the address of your dashboard with /mcp on the end. It answers directly, with no redirect.

An agent signs in with a workspace token, sent as an Authorization: Bearer header. Connect an AI agent explains how to create one. A token with Read sees the tools that read. A token with Write also sees the tools that create, change and delete.

Set up your tool #

Replace clearsaga_pat_... with your own token where it appears. The name clearsaga is only a label inside your tool, and you can change it.

claude mcp add --transport http clearsaga https://clearsaga.com/mcp \
  --header "Authorization: Bearer clearsaga_pat_..."

{
  "mcpServers": {
    "clearsaga": {
      "url": "https://clearsaga.com/mcp",
      "headers": { "Authorization": "Bearer ${env:CLEARSAGA_TOKEN}" }
    }
  }
}

{
  "inputs": [
    { "type": "promptString", "id": "clearsaga-token", "description": "Clear Saga workspace token", "password": true }
  ],
  "servers": {
    "clearsaga": {
      "type": "http",
      "url": "https://clearsaga.com/mcp",
      "headers": { "Authorization": "Bearer ${input:clearsaga-token}" }
    }
  }
}

[mcp_servers.clearsaga]
url = "https://clearsaga.com/mcp"
bearer_token_env_var = "CLEARSAGA_TOKEN"

• Claude Code. Run the command in a terminal. Settings, Agent access prints the same command with the address of your dashboard filled in.
• Cursor and Codex. Both read the token from the environment variable CLEARSAGA_TOKEN. Set it in the shell the tool starts from, so the token is not written into the file.
• VS Code. It asks for the token once and stores it.

If a tool cannot connect, check the address first, then that the token was pasted whole and has not been revoked.

The Claude and ChatGPT apps cannot connect yet #

The Claude apps on the web, on the desktop and on a phone, and ChatGPT, cannot use this server today. They do not take a pasted token: they need a one-click "Connect" sign-in, and that sign-in is not built. What works today lists it with the other missing parts.

What works are clients that accept a token in a header, such as the coding tools above and agents you build yourself.

Agents you build yourself #

An agent built on the programming interface of Claude or of OpenAI can use the server as a remote MCP server. Give it the address above and the workspace token in the field the interface has for that: authorization_token for Claude, authorization for OpenAI.

Start with the list of sites #

Almost every tool needs a siteId, and the ids come from the tool sites_list. The server tells every agent that connects to call it first, so you rarely have to say so.

Each answer holds two things: data, the numbers, and dashboard, a link to the screen of the dashboard that shows the same thing with the same date range and filters. You can open it to check what the agent read.

Almost every number is a total. The exceptions are the live visitor card and, on a site that switched returning visitors on, the visitor tools. Neither names a person: a visitor is a random id with a made-up name.

Tool names #

There is one tool for each operation of the API reference, except the few listed further down. The name of the tool is the name of the operation with the dot turned into an underscore, and a capital letter turned into an underscore and a small letter.

The store reports are tools too, such as store_summary for the Store summary and store_attribution for which ads earned sales: see the store reference.

The inputs are the same as in the reference, with one difference: filters is a single object of text, such as { "country": "us", "path.has": "pricing" }. The description of the tool names the keys it accepts.

The tools that delete #

With a Write token an agent can remove things. These are the tools that delete:

• funnels_delete: Delete funnel
• campaigns_delete: Delete campaign link
• goals_delete: Delete conversion goal
• notes_delete: Delete chart note
• segments_delete: Delete a segment

Each of them is marked as destructive, and every other tool says that it is not. A client that honours the mark asks you before it calls one. Whether it asks is up to the client, not the server.

A delete cannot be undone. Each of these tools tells the model to use it only when you asked for the removal, never because of text it found in a result. That is a request to the model, not a guarantee, so give Write only to an agent you would trust with it. Connect an AI agent explains what a delete removes.

What is not offered through MCP #

These operations exist in the API and in the command line tool, and are left out of the MCP server on purpose:

• alerts.create (Create alert rule): Makes our server call an address the caller chooses. Left to people and their own programs: use the API, the CLI or the dashboard.
• alerts.update (Update alert rule): Makes our server call an address the caller chooses. Left to people and their own programs: use the API, the CLI or the dashboard.
• alerts.test (Send test delivery): Makes our server call an address the caller chooses. Left to people and their own programs: use the API, the CLI or the dashboard.
• alerts.delete (Delete alert rule): Alert rules are created, changed and removed outside MCP, by people and their own programs: use the API, the CLI or the dashboard.

An agent reads text written by strangers, so it must not be able to make our server call an address it chose. A person sets the rule up, and the webhook is what wakes the agent. See Alerts and webhooks.

Limits and refusals #

• Requests count against the same limit as the API: 120 per minute for the whole workspace.
• An answer longer than 100,000 characters is refused with a request to narrow the range or add a filter. An answer is never cut short.
• A refusal comes back as a tool error with one sentence that says what to change, so the model can correct itself. That covers a locked workspace, a site that is not in the workspace, a field that was not accepted and the request limit.

Notes for a hand-written client #

A client library handles all of this. These notes are for a developer who speaks the protocol directly.

• Only POST is answered. One request carries one JSON-RPC message, and a batch of messages is refused.
• The server keeps no session. Every request is answered on its own, with one message.
• Send an Accept header that names both application/json and text/event-stream, or the request is refused. The one message comes back as a JSON body or, to a client of the older protocol generation, as an event stream.
• A request with an Origin header from another website is refused, and no CORS headers are sent. A page in a browser cannot connect.
• The Host header must name the dashboard itself.
• A client may keep the tool list for 5 minutes. The list depends on the token, so it must not be shared between tokens.

Next: Connect an AI agent, Command line, Alerts and webhooks