# MCP server

Capless speaks the [Model Context Protocol](https://modelcontextprotocol.io), so Claude Code, Cursor and any MCP client can set up tracking, read your data and run SQL for you.

* URL: `https://mcp.capless.sh/mcp` (Streamable HTTP)
* Auth: header `Authorization: Bearer cpl_…` (your project API key)

## Install

Claude Code:

```sh
claude mcp add --transport http capless https://mcp.capless.sh/mcp --header "Authorization: Bearer cpl_…"
```

Cursor (`.cursor/mcp.json`), and most other clients:

```json
{
  "mcpServers": {
    "capless": {
      "url": "https://mcp.capless.sh/mcp",
      "headers": { "Authorization": "Bearer cpl_…" }
    }
  }
}
```

No API key yet? The [signup API](https://capless.sh/docs/agents.md#signup-api) returns one, together with this exact config in `mcp`. Keep the key out of version control: use your client's user-level config or an environment variable.

## Tools

| Tool | What it does |
|---|---|
| `get_started` | Start here: what is set up in the project and what to do next |
| `list_sites` | Web analytics sites and their snippets |
| `create_site` | Create a site (`name`, `allowedOrigins`, `replaySampleRate`) |
| `list_streams` | Streams with entry counts and heads |
| `create_stream` | Create a stream with an optional CEL validator |
| `insert_entries` | Insert a batch atomically (idempotent with a key) |
| `read_stream` | Read entries with CEL `filter`/`map`, cursor pagination |
| `locate` | Find the cursor for a commit time |
| `erase_entries` | Erase entries matching a CEL predicate |
| `list_materializations` | ClickHouse materializations |
| `create_materialization` | Create an isolated ClickHouse database |
| `run_sql` | Run one ClickHouse SQL statement in a materialization |
| `connect_stream` | Connect a stream to a table (backfill, then follow) |
| `materialization_status` | Insert and deletion freshness per source |
| `get_usage` | This month's events and replays against your plan's allowance |
| `cel_reference` | The CEL environment: variables, limits, number and regex rules |
| `evaluate_cel` | Dry-run a CEL expression against a sample record before using it in a read, erasure or materialization |

Each tool maps onto the [HTTP API](https://capless.sh/docs/api.md) with the same semantics, limits and error codes.

## Things to ask

* "Is Capless installed correctly on this site? Check that events are arriving."
* "Which pages had rage clicks in the last 7 days?"
* "Set up a ClickHouse table for pageviews and show me the top referrers this month."
* "Delete all data for user `user_42` and confirm when it is purged."
* "How close are we to this month's event limit?"