dbtrail Documentation

dbtrail Cloud provides a hosted MCP endpoint that lets Claude and other AI assistants query your MySQL change history directly. Under the hood, the streaming and query capabilities are powered by the open-source dbtrail engine (the bintrail CLI) — Cloud adds multi-tenancy, managed infrastructure, and this AI integration layer on top. Connect from claude.ai, Claude Desktop, Claude Code, Cursor, or any compatible AI app. The Cloud convenience: there's no local software to install. If you run dbtrail self-hosted, the same capability is available by running the MCP server yourself — see Connect Claude (self-hosted).

Prerequisites

A dbtrail account with at least one registered server
An API key (generate one from Dashboard → Settings → API Keys)

Connection methods

Direct remote connection (recommended)

You just need a URL and an API key.

Go to Settings → Integrations → Add
URL: https://api.dbtrail.com/mcp
Add your API key as the auth header

Go to Settings → Integrations → Add remote integration
URL: https://api.dbtrail.com/mcp
Configure the API key as the authorization header

claude mcp add --transport http bintrail \
  https://api.dbtrail.com/mcp \
  --header "Authorization: Bearer bt_live_YOUR_API_KEY"

Add to your tool configuration:

{
  "mcpServers": {
    "bintrail": {
      "url": "https://api.dbtrail.com/mcp",
      "headers": {
        "Authorization": "Bearer bt_live_YOUR_API_KEY"
      }
    }
  }
}

npm stdio bridge (fallback)

For older AI apps that only support stdio transport, the bintrail-mcp npm package acts as a local bridge:

npx bintrail-mcp --api-key bt_live_YOUR_API_KEY

Or add to your app's tool config:

{
  "mcpServers": {
    "bintrail": {
      "command": "npx",
      "args": ["bintrail-mcp", "--api-key", "bt_live_YOUR_API_KEY"]
    }
  }
}

Prefer the remote endpoint

The direct remote connection is recommended for all apps that support it. The npm bridge is only needed for apps that exclusively support stdio.

Not the same as the open-source bintrail-mcp binary

The npm bintrail-mcp package shares its name with the open-source bintrail-mcp Go binary, but they are different things. The npm package is a thin stdio bridge that forwards requests to the Cloud endpoint using your API key. The Go binary is a standalone MCP server that connects directly to a self-hosted index via BINTRAIL_INDEX_DSN and takes no API key — see Connect Claude (self-hosted).

Why API keys

Some AI apps don't handle interactive login flows. API keys solve this by providing a static token that can be configured once. API keys are available on all plans (including Free).

Verifying the connection

After setup, try asking:

"What servers do I have in dbtrail?"

If the connection is working, you'll see a response listing your registered servers and their status.

Permissions

Connecting Claude requires the mcp:connect permission. The following roles have this permission:

Role	Access
owner	Yes
admin	Yes
operator	Yes
analyst	Yes
viewer	No

Claude gets the full Cloud tool set — the core query, recover, status, and list_schema_changes tools plus Cloud-only registry, aggregation, and forensics tools. See the Tools Reference and the MCP endpoint reference for the complete list.

Connect Claude (Cloud)