# MCP server

> Connect an AI agent to your workspace over the Model Context Protocol: the address, the setup for coding tools, and what the tools can do.

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.

> [!WARNING]
> No client has been tested against a live server. The server is covered by automated tests, but nobody has yet connected one of the tools below to a deployed Clear Saga. The setup blocks may need a detail adjusted for the version of the tool you use.

## The address and the token

The server has one address:

```text
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](/docs/agents) 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 Code**

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

**Cursor** (~/.cursor/mcp.json)

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

**VS Code** (.vscode/mcp.json)

```json
{
  "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}" }
    }
  }
}
```

**Codex** (~/.codex/config.toml)

```toml
[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](/docs/status) 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](/docs/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](/docs/api), 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.

| Operation | Tool |
| --- | --- |
| `sites.list` | `sites_list` |
| `funnels.create` | `funnels_create` |
| `overview.conversionPeak` | `overview_conversion_peak` |

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](/docs/api/store).

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](/docs/agents) 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](/docs/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](/docs/agents), [Command line](/docs/cli), [Alerts and webhooks](/docs/alerts-and-webhooks)