MCP Server

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:

{
  "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

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:

Environment variable — set TELL_API_KEY in your MCP client config
Per-tool parameter — pass api_key to any tool call
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:

list_workspaces — find your workspace ID
workspace_info — learn the data model before querying
run_board — use existing dashboards for standard metrics (DAU, MAU, events)
list_events — discover what’s being tracked
query — write SQL for ad-hoc analysis
explore_data — drill down into raw data
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 with execution time and row count.

What’s next

Blocks — the streaming block format that MCP tools use for generative UI
CLI Commands — tell mcp and other CLI tools
Ask — query your data with AI from the command line

CLI

AI Integration

Running Tell

Quick start

Stdio (Claude Desktop, Cursor, Zed)

HTTP/SSE

What you can do

Tools

Workspace discovery

Data discovery and querying

Boards

Data exploration

ML enrichment

User segments

Authentication

Permissions

Recommended workflow

SQL query security

What’s next

​Quick start

​Stdio (Claude Desktop, Cursor, Zed)

​HTTP/SSE

​What you can do

​Tools

​Workspace discovery

​Data discovery and querying

​Boards

​Sharing

​Data exploration

​ML enrichment

​User segments

​Authentication

​Permissions

​Recommended workflow

​SQL query security

​What’s next

Quick start

Stdio (Claude Desktop, Cursor, Zed)

HTTP/SSE

What you can do

Tools

Workspace discovery

Data discovery and querying

Boards

Sharing

Data exploration

ML enrichment

User segments

Authentication

Permissions

Recommended workflow

SQL query security

What’s next