MCP Server

Connect ZizkaDB to Claude Desktop, Cursor, or Windsurf in minutes — no SDK and no changes to your app code. The AI calls ZizkaDB tools directly during conversations.

Fastest start — Cursor: paste this into ~/.cursor/mcp.json, reload MCP, done.

json{
  "mcpServers": {
    "zizkadb": {
      "command": "uvx",
      "args": ["zizkadb-mcp"],
      "env": { "ZIZKADB_API_KEY": "zizkadb_live_xxxx" }
    }
  }
}

Self-host: use the full block in Self-hosted API below (only ZIZKADB_HOST — dev key auto-injected). Requires uvx — install uv first.

No install — connect by URL

ZizkaDB Cloud also runs the MCP server for you at https://db.zizka.ai/mcp (Streamable HTTP). Use it from any client that takes a server URL. Send your API key as Authorization: Bearer zizkadb_live_xxxx or X-ZizkaDB-API-Key. Same tools as the package; pass the event_id that log_event returns as parent_id on the next event to keep the causal chain.

json{
  "mcpServers": {
    "zizkadb": {
      "url": "https://db.zizka.ai/mcp",
      "headers": { "Authorization": "Bearer zizkadb_live_xxxx" }
    }
  }
}

MCP (Model Context Protocol) lets AI apps use external tools. ZizkaDB exposes log, search, why, time travel, and more as native MCP tools.

Prerequisites

uvx (recommended) — comes with uv install. Or: pip install "zizkadb-mcp>=0.1.12"

bash# macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh uvx --version

Create an agent & copy key

Claude Desktop

Edit Claude config

Mac:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\\Claude\\claude_desktop_config.json

Add ZizkaDB (merge into existing mcpServers if you have other servers):

json{
  "mcpServers": {
    "zizkadb": {
      "command": "uvx",
      "args": ["zizkadb-mcp"],
      "env": {
        "ZIZKADB_API_KEY": "zizkadb_live_xxxx"
      }
    }
  }
}

Restart Claude Desktop

Quit completely and reopen. ZizkaDB tools appear in the tool list (hammer icon). Claude can call them during any chat.

Cursor

Edit Cursor MCP config

Create or edit ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project:

json{
  "mcpServers": {
    "zizkadb": {
      "command": "uvx",
      "args": ["zizkadb-mcp"],
      "env": {
        "ZIZKADB_API_KEY": "zizkadb_live_xxxx"
      }
    }
  }
}

Reload MCP in Cursor

Quit Cursor completely (Cmd+Q) and reopen, or use Command Palette → MCP: Reload servers. Open Cmd+Shift+J → Tools & MCP to confirm zizkadb is connected.

Windsurf & other MCP clients

Same JSON block — point your client's MCP config at uvx zizkadb-mcp with ZIZKADB_API_KEY in env.

Self-hosted API

After bash scripts/setup-local.sh, paste this (no API key needed on localhost):

json{
  "mcpServers": {
    "zizkadb": {
      "command": "uvx",
      "args": ["zizkadb-mcp"],
      "env": {
        "ZIZKADB_HOST": "http://localhost:8000"
      }
    }
  }
}

Using MCP in practice

Once connected, ask the AI naturally — it will call tools when needed:

"Log that we decided to use Postgres for the billing service"

→ log_event

"What did we log about billing last week?"

→ search_memory

"Why did the agent call get_billing in event X?"

→ why

"What was the agent state on May 1 at 3pm?"

→ time_travel

All MCP tools

log_eventLog action with optional causal parent_id

search_memoryKeyword or hybrid search over agent history

verify_chainProve the agent's history is untouched

get_contextFormatted memory block for system prompts

whyCausal chain for an event_id

query_eventsList/filter recent events

time_travelLogged state at a past timestamp

memory_diffSession summary

forgetGDPR delete by metadata filter

Troubleshooting

Tools not showing

Restart the app after editing config. Check JSON is valid (no trailing commas).

uvx not found

Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh

Auth errors

Cloud: verify ZIZKADB_API_KEY. Self-host: set ZIZKADB_HOST to http://localhost:8000 and ensure local API is running (curl http://localhost:8000/health). Dev key is zizkadb_dev_local by default.