MCP Server

The Framedash MCP Server is a Model Context Protocol server that gives LLMs direct access to Framedash telemetry data. It provides 12 read-only tools and 4 resources, enabling natural-language queries against your game analytics.

For AI agents

Machine-readable entry points: the OpenAPI schema is at https://docs.framedash.dev/openapi.yaml, an index of these docs at https://docs.framedash.dev/llms.txt, and a full-text export at https://docs.framedash.dev/llms-full.txt.

Setup

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "framedash": {
      "command": "npx",
      "args": ["-y", "@framedash/mcp-server"],
      "env": {
        "FRAMEDASH_API_KEY": "fd_xxx",
        "FRAMEDASH_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

VS Code (Claude Extension)

Add to your VS Code settings:

{
  "claude.mcpServers": {
    "framedash": {
      "command": "npx",
      "args": ["-y", "@framedash/mcp-server"],
      "env": {
        "FRAMEDASH_API_KEY": "fd_xxx",
        "FRAMEDASH_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

Windows

On Windows, replace "command": "npx" with "command": "cmd" and prepend "/c" to the args array:

"command": "cmd",
"args": ["/c", "npx", "-y", "@framedash/mcp-server"]

Claude Code

Register the server with the claude mcp command:

claude mcp add framedash \
  -e FRAMEDASH_API_KEY=fd_xxx \
  -e FRAMEDASH_PROJECT_ID=your-project-uuid \
  -- npx -y @framedash/mcp-server

Use a Full preset key to enable every tool (including raw SQL query), or a Read-only key for the non-SQL analytics tools.

Hosted remote endpoint

Framedash also hosts a remote MCP server, so MCP clients that support remote servers and OAuth need no local install. Send requests to POST {origin}/api/mcp (default https://app.framedash.dev/api/mcp) over the Streamable HTTP transport. The endpoint is stateless: it uses no session IDs.

Authentication is OAuth 2.1 Bearer only; API keys are not accepted here. A 401 response carries a WWW-Authenticate header whose resource_metadata points at {origin}/.well-known/oauth-protected-resource, so a client that implements the MCP authorization spec can discover the authorization server and complete the OAuth flow on its own, including dynamic client registration. Tool calls run under the granted scopes and projects, exactly as on the REST API. GET and DELETE return 405. The raw SQL query tool is not available over the remote endpoint: it needs the data:admin scope, which OAuth tokens can never carry, so raw SQL stays with the stdio server and a Full API key.

The remote endpoint has a separate per-IP rate limit at its pre-auth entry point, in addition to the per-account plan rate limit. See Rate Limits in the API Overview for details.

Use the hosted endpoint as the zero-install alternative to the stdio server for MCP clients with remote-server and OAuth support. The stdio server (npx -y @framedash/mcp-server) remains the choice for API-key-based or local setups.

Environment Variables

Variable	Required	Description
FRAMEDASH_API_KEY	Yes	API key with scopes required by the tools you use. The Full preset covers every MCP tool, including raw SQL query; the Read-only preset covers the non-SQL analytics tools.
FRAMEDASH_PROJECT_ID	No	Default project UUID
FRAMEDASH_BASE_URL	No	API base URL (default: https://app.framedash.dev)

Note

If FRAMEDASH_PROJECT_ID is omitted, project-scoped tools still work but require an explicit project_id argument per call.

Tools

Query

Tool	Description	Arguments
query	Execute a read-only SQL query against the ClickHouse events table	sql (string, required), project_id (uuid, optional), limit (int 1-1000, default 100)

Analytics

Tool	Description	Arguments
get_dashboard	Project KPIs (DAU, MAU, sessions, events)	project_id (uuid, optional), days (7/14/30/90, default 30)
get_retention	Cohort retention analysis	project_id (uuid, optional), days (7/14/30/90, default 30)
get_funnel	Event funnel analysis	project_id (uuid, optional), steps (string, required: comma-separated 2-8 event names), days (7/14/30/90, default 30)
get_insights	Aggregated insights by dimension	project_id (uuid, optional), metric (count/unique_players, required), group_by (string, required: event_name, platform, etc.), days (7/14/30/90, default 30), limit (10/20/50), event_name (string, optional)
get_heatmap	Heatmap grid data for a map	project_id (uuid, optional), map_id (string, required), cell_size (5/10/25/50, default 25), days (1/7/14/30, default 7), event_name (string, optional)

Project

Tool	Description	Arguments
list_projects	Show projects bound to the API key	(none)
get_project_status	Project health overview (event counts, last event time)	project_id (uuid, optional)
list_maps	List maps in the project	project_id (uuid, optional)
list_content	List content registry entries	project_id (uuid, optional), type (string, optional)

Alerts

Tool	Description	Arguments
list_alerts	List alert rules	project_id (uuid, optional)
get_alert_history	Alert trigger/resolve history	project_id (uuid, optional), limit (int 1-100, default 50)

Resources

Data is also available as MCP resources via the framedash:// URI scheme:

URI	Description
framedash://projects	Projects bound to the API key
framedash://projects/{projectId}/maps	Maps with coordinates and bounds
framedash://projects/{projectId}/content	Content registry entries
framedash://projects/{projectId}/status	Project health and statistics

Example Prompts

Once the MCP Server is configured, you can query your data in natural language:

Prompt	Tool Used
”Show me DAU for the last 7 days”	get_dashboard (days=7)
“Analyze the funnel from spawn to death”	get_funnel (steps=“player_spawn,player_death”)
“Break down event counts by platform”	get_insights (metric=count, group_by=platform)
“Show the FPS heatmap for my map”	get_heatmap (map_id=…)
”Check recent alert history”	get_alert_history

Next Steps

• API Reference: REST API details
• CLI Reference: Command-line tool