MCP Server

The Databuddy MCP server lets AI agents (Claude, Cursor, Windsurf, or any MCP-compatible client) query your analytics, manage feature flags, triage errors, and more through a standard protocol.

Endpoint

The server uses the Streamable HTTP transport (JSON-RPC over HTTP). No SSE or WebSocket connection required.

Alternate transport surfaces are also available at https://api.databuddy.cc/mcp and https://api.databuddy.cc/.well-known/mcp for WebMCP-capable agents.

Discovery Manifest

Agents can discover the Databuddy MCP server from either well-known manifest URL:

The manifest includes the Streamable HTTP endpoint, API-key auth header, required scopes, related OpenAPI spec, and a ready-to-use MCP client config template.

Authentication

Pass an API key with the read:data scope:

{
"mcpServers": {
  "databuddy": {
    "type": "http",
    "url": "https://api.databuddy.cc/v1/mcp/",
    "headers": {
      "x-api-key": "dbdy_your_api_key_here"
    }
  }
}
}

Dashboard setup

The dashboard creates a dedicated automation key tagged MCP rather than requiring you to share a personal API key. The setup sheet defaults to read-only analytics, then lets you enable Workspace actions (goals, funnels, annotations, and investigation replies), Feature flags, and Short links. Each capability maps to the narrowest scopes currently supported by the MCP tools. You can create separate connections for Cursor, Claude, Windsurf, or another MCP client, scope a connection to specific websites, choose a 90-day expiry or no expiry, and rotate or revoke it later from Organization Settings → API Keys.

For clients that support environment-variable interpolation in remote MCP headers, enable the environment-variable option in the setup sheet and set DATABUDDY_API_KEY before launching the client. Otherwise, paste the generated one-time config with the secret in the x-api-key header.

Client Setup

Claude Code / Claude Desktop

Add to your .mcp.json or Claude Desktop config:

{
"mcpServers": {
  "databuddy": {
    "type": "http",
    "url": "https://api.databuddy.cc/v1/mcp/",
    "headers": {
      "x-api-key": "dbdy_your_api_key_here"
    }
  }
}
}

Cursor / Windsurf

Add to your MCP settings (typically .cursor/mcp.json or workspace settings):

{
"mcpServers": {
  "databuddy": {
    "type": "http",
    "url": "https://api.databuddy.cc/v1/mcp/",
    "headers": {
      "x-api-key": "dbdy_your_api_key_here"
    }
  }
}
}

Available Tools

Analytics

Investigations

reply_to_investigation returns the durable reply status immediately. If it is queued or running, call get_investigation with the same investigation ID until the reply is succeeded or failed; the new outcome appears in that timeline.

Funnels & Goals

Annotations

Feature Flags

Links

Conventions

Website selection: Any tool that needs a website accepts websiteId, websiteName, or websiteDomain. Pass one.

Dates: Use a preset (e.g. last_7d, last_30d) OR both from and to (YYYY-MM-DD). Defaults to last_7d. Passing only one of from/to is rejected.

Filters: The field value is the ClickHouse column name. Use get_schema when uncertain. Error messages suggest close matches on typos.

Mutations: When a tool exposes confirmed, preview with confirmed: false, then execute with confirmed: true. Investigation replies use a stable replyId for safe retries instead.

Example Usage

Batch multiple queries in a single get_data call:

{
"tool": "get_data",
"arguments": {
  "websiteDomain": "example.com",
  "queries": [
    { "type": "summary_metrics", "preset": "last_7d" },
    { "type": "top_pages", "preset": "last_7d", "limit": 5 },
    { "type": "top_referrers", "preset": "last_7d", "limit": 5 },
    { "type": "error_summary", "preset": "last_7d" }
  ]
}
}

Filter errors by type:

{
"tool": "get_data",
"arguments": {
  "websiteDomain": "example.com",
  "type": "recent_errors",
  "preset": "last_7d",
  "limit": 20,
  "filters": [
    { "field": "error_type", "op": "eq", "value": "TypeError" }
  ]
}
}

Resources

The server exposes a databuddy://guide resource with extended workflow tips and known footguns. MCP clients that support resources can read it for additional context.

Scopes & Access Control

Tools are filtered based on your API key's scopes:

Session-authenticated users (via the dashboard) get access based on their organization role instead.