Skip to main content

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.

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

ToolWhat it does
list_workspacesList workspaces you have access to with your role in each

​
Data discovery and querying

ToolWhat it does
workspace_infoGet the complete data model — tables, columns, relationships, query patterns. Call this first before writing SQL.
list_columnsList column names and types for a specific table (Admin+)
queryExecute a read-only SQL query against your analytics data (Admin+)

​
Boards

ToolWhat it does
list_boardsList dashboards in a workspace
get_boardGet a board’s full configuration — blocks, series, visualizations
create_boardCreate a new dashboard with metric blocks
update_boardUpdate a board’s title, description, or blocks
delete_boardPermanently delete a board
run_boardExecute all metric series in a board and return the results

​
Sharing

ToolWhat it does
share_boardCreate a public share link for a board
get_share_linkCheck if a board has an existing share link

​
Data exploration

ToolWhat it does
list_eventsDiscover top events by count and percentage
explore_dataBrowse raw rows from events, sessions, users, or logs with filters

​
ML enrichment

ToolWhat it does
enrichment_statusCheck if ML predictions are active and how many events are enriched
churn_riskFind users most likely to churn, sorted by risk score
anomaly_summarySummarize anomalous log patterns by source
segment_overviewShow user distribution across ML-assigned segments

​
User segments

ToolWhat it does
list_segmentsList available segment definitions (lifecycle and engagement)
segment_countsCount users per segment with percentages
segment_usersList 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:
ToolRequired role
queryAdmin+ (raw SQL access)
list_columnsAdmin+ (schema inspection)
Board updates and deletions require board ownership or Admin role. 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 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