Claude Setup

dbtrail exposes your change history to Claude (and any MCP-capable client) through six read-only tools: search changes, draft reversal SQL, draft reversal SQL for foreign-key cascade side effects, reconstruct a row's state at a point in time, show index status, list schema changes. The AI sees exactly what the web console shows you, with the same result caps and the same redactions. It never executes SQL and never connects to your source database: recovery SQL is text you review and run yourself. (Time travel needs a backup configured for that server, exactly like the row-state section of the console's Restore view; without one the tool says so.)

The web console serves MCP directly at /mcp: no separate server to run. Everything on this page starts from one place: open the console → Settings → Connect AI. That page shows your MCP URL, checks that a token is configured, offers the Claude Desktop bundle for download, and has copy-paste snippets for every other client. Below those steps, a Connect a SQL client panel does the same for the time-travel SQL port, which is a different way in: see Time-Travel SQL.

Step 0: generate a token

MCP clients authenticate with an access token: the username/password you use in the browser does not work for them. Since v0.40.0 you mint one without leaving the UI:

Open Settings → Connect AI. If no token is configured, the Access token card has a Generate token button. Click it and copy the value it shows. It appears exactly once and is never stored (only its hash is); the same card rotates or revokes it later, no restart needed. The generated token grants the read-only MCP tools only; it cannot administer the console.

That's the whole step. The token is worth protecting: anyone holding it can read your change history, row images included. Treat it like a database credential.

Step 1: copy your MCP URL

Settings → Connect AI shows it, e.g. http://your-host:8090/mcp.

• Multiple servers? /mcp targets the console's default server; /mcp/{name} targets a specific one. The card shows the URL for whichever server you have selected in the sidebar.
• The URL only needs to be reachable from the machine where the AI client runs: LAN, VPN, or an SSH port-forward are all fine. Nothing needs to be on the public internet.

Step 2: connect your client

{
  "mcpServers": {
    "dbtrail": {
      "command": "bintrail-mcp",
      "args": ["--connect", "http://your-host:8090/mcp", "--token", "YOUR_CONSOLE_TOKEN"]
    }
  }
}

Step 3: ask something

Open a new conversation. The query, recover, recover_cascade, reconstruct, status, and list_schema_changes tools are now available. Try:

"What's the status of my binlog index?"

"Someone fat-fingered an UPDATE on users around 3pm. What did it change, and write me the SQL to undo it."

If the connection is working, Claude calls the tools and answers from the index; it never touches the source database. From there, head to Using Claude with dbtrail for example conversations, or the Tools Reference.

When something doesn't work

The most common failures: 401 (wrong token, or a port-forward pointing at a stale process), 403 "no token configured" (add --token / BINTRAIL_CONSOLE_TOKEN and restart), and connection refused (the URL isn't reachable from the AI client's machine; check curl http://host:8090/api/healthz from there). The full symptom table is in the repository: Connect an AI assistant → troubleshooting.

Headless setups (no console)

CLI-only deployments can run the standalone bintrail-mcp server against the index DSN directly, over stdio for local clients or --http for remote ones. Every option and knob: MCP server reference.