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

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

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.