Tools Reference
Complete reference for the tools available to Claude via dbtrail
The following tools are available to Claude and other AI assistants connected to dbtrail — whether through the open-source bintrail-mcp server or the dbtrail Cloud MCP gateway. The core tools (query, recover, status, list_schema_changes) exist in both editions; Cloud adds a set of tenant- and forensics-oriented tools on top.
Edition differences
- Self-hosted (
bintrail-mcp) — tools read the index database directly. Passindex_dsnon each call or set theBINTRAIL_INDEX_DSNenvironment variable. Tools additionally acceptformat(json/table/csv),column_eq,flag,no_archive, andprofile(a named access profile applying table-level deny rules and column redaction). The server runs over stdio by default, or as a Streamable HTTP server with--http <addr>. - dbtrail Cloud — tools route by
server_id(a UUID fromlist_servers) to the tenant's registered servers, and every call is subject to access rules and role permissions.queryaddsorderandinclude_forensics. See Claude setup to connect.
The Editions column in the parameter tables below indicates which edition accepts each parameter.
Core tools — both editions
query
Search indexed binlog changes by schema, table, time range, or event type.
Parameters
| Parameter | Type | Editions | Description |
|---|---|---|---|
server_id | string | Cloud | UUID of the registered server (required; from list_servers) |
index_dsn | string | Self-hosted | MySQL DSN of the index database (optional if BINTRAIL_INDEX_DSN is set) |
schema | string | both | Database schema name (required on Cloud; optional filter self-hosted) |
table | string | both | Table name (required on Cloud; optional filter self-hosted) |
event_type | string | both | INSERT, UPDATE, or DELETE |
pk | string | both | Filter by primary key value (use | for composites, e.g. 12345|2) |
gtid | string | both | Filter by GTID (e.g. 3e11fa47-...:42) |
changed_column | string | both | Filter UPDATEs by changed column name (e.g. email) |
since | string | both | Start time (ISO 8601; self-hosted also accepts YYYY-MM-DD HH:MM:SS) |
until | string | both | End time |
limit | integer | both | Max results (default: 100; Cloud caps at 1000) |
order | string | Cloud | ASC (oldest first) or DESC (newest first, default) |
include_forensics | boolean | Cloud | Enrich events with who made the change (user, host, program). Default: false |
column_eq | array | Self-hosted | column=value filters matched against the before/after row images (repeat for AND; literal NULL matches JSON null) |
flag | string | Self-hosted | Filter events from tables or columns carrying this flag |
format | string | Self-hosted | Output format: json (default), table, or csv |
profile | string | Self-hosted | Apply a named access profile (table-level deny + column redaction) |
no_archive | boolean | Self-hosted | Disable auto-routing to Parquet archives (MySQL-only results) |
Response
Both editions return the matching change events, each containing:
event_type— INSERT, UPDATE, or DELETEtimestamp— when the change occurredschema/table— where the change happenedprimary_key— primary key of the affected rowbefore— row state before the change (null for INSERTs)after— row state after the change (null for DELETEs)
On Cloud the events are wrapped in a JSON envelope with success, total_count (the true total number of matching events regardless of limit), and has_more. Self-hosted, the events are rendered in the requested format (JSON by default), with a truncation warning when results hit the limit.
dbtrail Cloud: total_count vs events length
On Cloud, total_count reflects the real number of matching events in the index, not the number of events returned. If you only need the count (not the events themselves), use the Cloud-only count_events tool instead — it's much more efficient.
recover
Generate SQL statements to reverse database changes. Always runs in dry-run mode — the SQL is generated but never executed.
Parameters
| Parameter | Type | Editions | Description |
|---|---|---|---|
server_id | string | Cloud | UUID of the registered server (required) |
index_dsn | string | Self-hosted | MySQL DSN of the index database (optional if BINTRAIL_INDEX_DSN is set) |
schema | string | both | Database schema name (required on Cloud; optional filter self-hosted) |
table | string | both | Table name (required on Cloud; optional filter self-hosted) |
gtid | string | both | Reverse the events of a specific transaction (GTID) |
since | string | both | Start of the search window |
primary_keys | array | Cloud | Primary key values to recover |
target_time | string | Cloud | ISO 8601 point-in-time to recover to |
pk | string | Self-hosted | Filter by primary key value (pipe-delimited for composites) |
event_type | string | Self-hosted | Only reverse INSERT, UPDATE, or DELETE events |
until | string | Self-hosted | End of the search window |
changed_column | string | Self-hosted | Only reverse UPDATEs that modified this column |
column_eq | array | Self-hosted | column=value filters matched against the row images |
flag | string | Self-hosted | Filter events from tables or columns carrying this flag |
limit | integer | Self-hosted | Max events to reverse (default: 1000) |
profile | string | Self-hosted | Apply a named access profile |
no_archive | boolean | Self-hosted | Disable auto-routing to Parquet archives |
Response
Both editions return the recovery SQL for review — it is never executed automatically.
- Self-hosted — a
BEGIN/COMMIT-wrapped SQL script that reverses events in reverse chronological order (most recent first), with a trailing comment noting the number of reversal statements generated. - dbtrail Cloud — a JSON envelope with
success,sql(transaction-wrapped),affected_rows,operations, andwarnings.
Recovery logic
| Original event | Generated SQL |
|---|---|
| DELETE | INSERT INTO ... (restores deleted row) |
| UPDATE | UPDATE ... SET (reverts to previous values) |
| INSERT | DELETE FROM ... (removes inserted row) |
dbtrail Cloud
Cloud recovery is FK-aware by default. resolve_fk (default true) walks up the FK chain to restore deleted parent rows first (up to 5 levels deep); include_dependents: true walks down to include deleted child rows; statements are topologically sorted so parents are inserted before children, and circular or self-referencing FKs are handled with SET FOREIGN_KEY_CHECKS=0/1. The response adds recovery_steps — an ordered list of steps, each with a reason — and warnings for skipped tables, depth limits, or detected cycles. Self-hosted recover applies reverse-chronological ordering only, with no FK-graph analysis. See Recover API — FK resolution for details.
status
Report the current state of the index and stream.
Parameters
| Parameter | Type | Editions | Description |
|---|---|---|---|
server_id | string | Cloud | UUID of a registered server (omit for the most recent active server) |
index_dsn | string | Self-hosted | MySQL DSN of the index database (optional if BINTRAIL_INDEX_DSN is set) |
Response
- Self-hosted — which binlog files have been indexed, the partition layout with estimated row counts, and an aggregate summary of indexed events.
- dbtrail Cloud — stream health (running / idle / not running), last checkpoint and last event time, and index coverage: total, live, and archived event counts, schema changes, earliest and latest event, and any uncovered DDLs.
list_schema_changes
List DDL schema changes — CREATE, ALTER, DROP, RENAME, TRUNCATE — recorded during binlog indexing or streaming. Use it to audit schema modifications or correlate structural changes with data anomalies.
Parameters
| Parameter | Type | Editions | Description |
|---|---|---|---|
server_id | string | Cloud | UUID of the registered server (required) |
index_dsn | string | Self-hosted | MySQL DSN of the index database (optional if BINTRAIL_INDEX_DSN is set) |
schema | string | both | Filter by schema name |
table | string | both | Filter by table name |
ddl_type | string | Self-hosted | Filter by DDL type: CREATE, ALTER, DROP, RENAME, or TRUNCATE |
since | string | both | Start time filter |
until | string | both | End time filter |
limit | integer | both | Max changes to return (default: 50 on Cloud, 100 self-hosted; Cloud caps at 1000) |
Response
Each change includes the timestamp, affected schema and table, DDL type, the full DDL statement, and binlog coordinates (file, position, GTID). On Cloud the list is wrapped in a JSON envelope with success, total_count, and has_more; servers on an older index format may omit the full statement and coordinates.
Cloud-only tools
The following tools require the dbtrail Cloud control plane (the tenant server registry and the forensics pipeline) and are not part of the self-hosted bintrail-mcp server:
| Tool | What it does |
|---|---|
list_servers | List the tenant's registered MySQL servers — returns each server's id (used as server_id in other tools), name, host, port, and status. |
list_tables | List schemas and tables with indexed binlog data on a server. Call before query or recover to discover valid names. |
count_events | Count indexed change events with optional group_by (schema, table, event_type) — much more efficient than query for volume questions. |
forensics_capabilities | Check which forensic data sources a server offers: performance_schema status and consumers, and audit log plugin installation. |
who_changed | Trace who modified a specific row, with forensic enrichment (user, host, program) when available. |
user_activity | List recent SQL statements by a MySQL user from performance_schema, with query text, duration, and rows affected. |
connection_history | Show connections from a MySQL user or host/IP, with database, command state, and running query. |
See the Cloud MCP API for endpoint details and Forensics for how the four forensic tools work and how to enable richer data sources on your server.
Access control
Self-hosted, pass profile on query or recover to apply a named access profile — table-level deny rules plus column redaction. While a profile is active, Parquet archive routing is disabled (archive queries do not enforce profile rules).
dbtrail Cloud
Several Cloud tools enforce access rules: query and batch_query strip unauthorized columns from before/after images and remove forensic SQL text when columns are restricted; count_events, who_changed, and recover enforce table-level access and likewise redact forensic SQL text. If the connected user's role has no access to the queried table, the tool returns an error.
dbtrail Cloud
All Cloud tools require the mcp:connect permission, which is available to analysts, operators, admins, and owners — viewers do not have access. The REST API endpoints have additional per-operation permission requirements (e.g. recover:execute for the /recover endpoint). See Team management.