> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tell.rs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> 21 tools for AI assistants via stdio and HTTP/SSE transports.

Tell includes an MCP (Model Context Protocol) server that gives AI assistants direct access to your analytics. Connect it to Claude Desktop, Cursor, Zed, or any MCP-compatible client — then ask questions about your data in natural language.

## Quick start

### Stdio (Claude Desktop, Cursor, Zed)

Add Tell to your MCP client configuration:

```json theme={null}
{
  "mcpServers": {
    "tell": {
      "command": "tell",
      "args": ["mcp"],
      "env": {
        "TELL_API_KEY": "tell_your_api_key"
      }
    }
  }
}
```

### HTTP/SSE

If your Tell server has MCP enabled, connect via HTTP:

```
POST https://your-tell-server/api/v1/mcp
```

The HTTP transport supports SSE for streaming responses with automatic reconnection.

## What you can do

Once connected, ask your AI assistant things like:

* "Show me daily active users for the last 30 days"
* "Which events are tracked most frequently?"
* "Find users most likely to churn"
* "Create a dashboard with DAU, WAU, and top events"
* "Are there any anomalies in the logs?"

The assistant uses Tell's 21 tools behind the scenes to query data, build dashboards, and surface insights.

## Tools

### Workspace discovery

| Tool              | What it does                                              |
| ----------------- | --------------------------------------------------------- |
| `list_workspaces` | List workspaces you have access to with your role in each |

### Data discovery and querying

| Tool             | What it does                                                                                                      |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `workspace_info` | Get the complete data model — tables, columns, relationships, query patterns. Call this first before writing SQL. |
| `list_columns`   | List column names and types for a specific table (Admin+)                                                         |
| `query`          | Execute a read-only SQL query against your analytics data (Admin+)                                                |

### Boards

| Tool           | What it does                                                      |
| -------------- | ----------------------------------------------------------------- |
| `list_boards`  | List dashboards in a workspace                                    |
| `get_board`    | Get a board's full configuration — blocks, series, visualizations |
| `create_board` | Create a new dashboard with metric blocks                         |
| `update_board` | Update a board's title, description, or blocks                    |
| `delete_board` | Permanently delete a board                                        |
| `run_board`    | Execute all metric series in a board and return the results       |

### Sharing

| Tool             | What it does                                |
| ---------------- | ------------------------------------------- |
| `share_board`    | Create a public share link for a board      |
| `get_share_link` | Check if a board has an existing share link |

### Data exploration

| Tool           | What it does                                                       |
| -------------- | ------------------------------------------------------------------ |
| `list_events`  | Discover top events by count and percentage                        |
| `explore_data` | Browse raw rows from events, sessions, users, or logs with filters |

### ML enrichment

| Tool                | What it does                                                        |
| ------------------- | ------------------------------------------------------------------- |
| `enrichment_status` | Check if ML predictions are active and how many events are enriched |
| `churn_risk`        | Find users most likely to churn, sorted by risk score               |
| `anomaly_summary`   | Summarize anomalous log patterns by source                          |
| `segment_overview`  | Show user distribution across ML-assigned segments                  |

### User segments

| Tool             | What it does                                                  |
| ---------------- | ------------------------------------------------------------- |
| `list_segments`  | List available segment definitions (lifecycle and engagement) |
| `segment_counts` | Count users per segment with percentages                      |
| `segment_users`  | List users in a specific segment with stats                   |

## Authentication

Tools authenticate using an API key. You can provide it in three ways:

1. **Environment variable** — set `TELL_API_KEY` in your MCP client config
2. **Per-tool parameter** — pass `api_key` to any tool call
3. **Environment reference** — use `env:MY_VAR_NAME` to read from an environment variable

Workspace-scoped API keys restrict access to a single workspace. User-level keys allow access to all workspaces the user belongs to.

## Permissions

Most tools work with any authenticated user. Two tools require Admin or higher:

| Tool           | Required role              |
| -------------- | -------------------------- |
| `query`        | Admin+ (raw SQL access)    |
| `list_columns` | Admin+ (schema inspection) |

Board updates and deletions require board ownership or Admin role.

## Recommended workflow

The MCP server includes instructions that guide AI assistants through the best workflow:

1. **`list_workspaces`** — find your workspace ID
2. **`workspace_info`** — learn the data model before querying
3. **`run_board`** — use existing dashboards for standard metrics (DAU, MAU, events)
4. **`list_events`** — discover what's being tracked
5. **`query`** — write SQL for ad-hoc analysis
6. **`explore_data`** — drill down into raw data
7. **`enrichment_status`**, **`churn_risk`** / **`anomaly_summary`** — check ML insights

## SQL query security

The `query` tool enforces multiple layers of protection:

* **SELECT only** — no INSERT, UPDATE, DELETE, DROP, or ALTER
* **Workspace scoping** — queries are automatically scoped to your workspace
* **Function blocking** — 40+ dangerous functions are blocked (file access, remote connections, system info)
* **No cross-workspace access** — queries can't reference other workspace databases

All queries are [audit logged](/running-tell/audit-privacy) with execution time and row count.

## What's next

* [Blocks](/tools/blocks) — the streaming block format that MCP tools use for generative UI
* [CLI Commands](/tools/commands) — `tell mcp` and other CLI tools
* [Ask](/tools/ask) — query your data with AI from the command line