Tools Reference
Complete reference for the tools available to Claude via the bintrail-mcp server
The following tools are available to Claude and other AI assistants connected to dbtrail. All six are read-only (annotated ReadOnlyHint: true and IdempotentHint: true). They read the index and never touch your source database.
There are two ways to serve them:
- The web console's
/mcpendpoint (recommended, see Claude Setup): authenticated with the console token, with the server selected by URL path (/mcpfor the default server,/mcp/{name}for a specific one). Responses carry the console's result caps and field redactions, and theindex_dsnparameter does not apply: the console owns the connection. - The standalone
bintrail-mcpserver (headless setups): reads the index database directly via theBINTRAIL_INDEX_DSNenvironment variable, or a per-callindex_dsnparameter that overrides it. Runs over stdio by default, or as a Streamable HTTP server with--http <addr>; see the MCP server reference.
query
Search indexed binlog changes by schema, table, time range, or event type.
Parameters
| Parameter | Type | Description |
|---|---|---|
index_dsn | string | MySQL DSN of the index database (optional if BINTRAIL_INDEX_DSN is set) |
schema | string | Database schema name |
table | string | Table name |
event_type | string | INSERT, UPDATE, or DELETE |
pk | string | Filter by primary key value (use | for composites, e.g. 12345|2) |
gtid | string | Filter by GTID (e.g. 3e11fa47-...:42) |
changed_column | string | Filter UPDATEs by changed column name (e.g. email) |
since | string | Start time (ISO 8601 or YYYY-MM-DD HH:MM:SS) |
until | string | End time |
limit | integer | Max results (default: 100) |
column_eq | array | column=value filters matched against the before/after row images (repeat for AND; literal NULL matches JSON null) |
flag | string | Filter events from tables or columns carrying this flag |
format | string | Output format: json (default), table, or csv |
profile | string | Apply a named access profile (table-level deny + column redaction) |
no_archive | boolean | Disable auto-routing to Parquet archives (MySQL-only results) |
Response
The matching change events, rendered in the requested format (JSON by default), with a truncation warning when results hit the limit. Each event contains:
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)
When Parquet archives are configured, results are automatically merged from the live index and the archives.
recover
Generate SQL statements to reverse database changes. Always runs in dry-run mode: dbtrail generates the SQL but never executes it.
Parameters
| Parameter | Type | Description |
|---|---|---|
index_dsn | string | MySQL DSN of the index database (optional if BINTRAIL_INDEX_DSN is set) |
schema | string | Database schema name |
table | string | Table name |
pk | string | Filter by primary key value (pipe-delimited for composites) |
event_type | string | Only reverse INSERT, UPDATE, or DELETE events |
gtid | string | Reverse the events of a specific transaction (GTID) |
since | string | Start of the search window |
until | string | End of the search window |
changed_column | string | Only reverse UPDATEs that modified this column |
column_eq | array | column=value filters matched against the row images |
flag | string | Filter events from tables or columns carrying this flag |
limit | integer | Max events to reverse (default: 1000) |
profile | string | Apply a named access profile |
no_archive | boolean | Disable auto-routing to Parquet archives |
Response
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. The SQL comes back for review. Nothing executes automatically.
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) |
status
Report the current state of the index and stream.
Parameters
| Parameter | Type | Description |
|---|---|---|
index_dsn | string | MySQL DSN of the index database (optional if BINTRAIL_INDEX_DSN is set) |
Response
Which binlog files have been indexed, the partition layout with estimated row counts, and an aggregate summary of indexed events.
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 | Description |
|---|---|---|
index_dsn | string | MySQL DSN of the index database (optional if BINTRAIL_INDEX_DSN is set) |
schema | string | Filter by schema name |
table | string | Filter by table name |
ddl_type | string | Filter by DDL type: CREATE, ALTER, DROP, RENAME, or TRUNCATE |
since | string | Start time filter |
until | string | End time filter |
limit | integer | Max changes to return (default: 100) |
Response
Each change includes the timestamp, affected schema and table, DDL type, the full DDL statement, and binlog coordinates (file, position, GTID).
recover_cascade
Generate reversal SQL for rows hit by a foreign-key ON DELETE / ON UPDATE CASCADE or SET NULL. InnoDB runs FK cascades below the binlog, so plain recover reverses only the parent change and silently misses the cascade-deleted children and the rewritten or nulled child foreign keys. This tool synthesizes those from the index and reverses them too. Dry-run only, like recover.
Parameters
| Parameter | Type | Description |
|---|---|---|
index_dsn | string | MySQL DSN of the index database (optional if BINTRAIL_INDEX_DSN is set) |
schema | string | Schema of the parent table whose change cascaded (required) |
table | string | Parent table whose cascade touched children (required) |
pk | string | Restrict to a single changed parent primary key (pipe-delimited for composites) |
pks | array | Restrict to several changed parent primary keys; mutually exclusive with pk |
since | string | Only parent changes at or after this time |
until | string | Only parent changes at or before this time |
lookback | string | How far before each parent change to search for child state (default 30d) |
max_depth | integer | Maximum cascade recursion depth, parent → child → grandchild (default 5) |
limit | integer | Max parent events to process, applied separately to the DELETE and the UPDATE scan (default 1000) |
allow_incomplete | boolean | Return the script even when the synthesis is provably partial (default false: any coverage caveat fails the call, with the caveats in the error) |
baseline_dir | string | Local baseline snapshot directory, enabling the Phase-2 fallback (also recovers children untouched within the lookback window) |
baseline_s3 | string | S3 prefix of baseline snapshots, used only when baseline_dir is unset |
Response
The reversal SQL plus a structured coverage report: statement count, how many parent rows were reversed (split into deletes and key-changing updates), how many child rows were re-INSERTed, how many SET NULL and key restores were emitted, and two separate channels: incomplete (every reason the recovery is provably partial) and warnings (advisory notes on an otherwise-complete recovery). complete is exactly "incomplete is empty".
reconstruct
Reconstruct a single row's full state at a point in time. It folds a baseline snapshot with the events indexed after it, so columns never touched inside the retained window still resolve, which recover cannot do because it only reverses the events it has. Requires a baseline snapshot: a backup created from the console's Backups page, or the CLI dump → baseline pipeline.
Parameters
| Parameter | Type | Description |
|---|---|---|
index_dsn | string | MySQL DSN of the index database (optional if BINTRAIL_INDEX_DSN is set) |
schema | string | Database schema name (required) |
table | string | Table name (required) |
pk | string | Primary key of the row to reconstruct (pipe-delimited for composites) (required) |
at | string | Point in time to reconstruct at (YYYY-MM-DD HH:MM:SS or RFC 3339, default now) |
history | boolean | Return every state transition from the baseline up to the target time instead of a single state |
baseline_dir | string | Local directory of baseline Parquet snapshots (overrides BINTRAIL_BASELINE_DIR) |
baseline_s3 | string | S3 prefix of baseline snapshots, used only when baseline_dir is unset |
allow_gaps | boolean | Proceed even when part of the window is missing from the captured history. Default false: a coverage gap, or a permanent capture loss recorded by the stream, aborts rather than returning a silently wrong row state. What was overridden comes back in warnings |
Response
The row's state at at, with the baseline it was folded from (baseline_time), how many events were applied (event_count), and flags distinguishing the three outcomes: the state, deleted as of that time (deleted), and no baseline row for that PK (found: false). With history: true, each transition carries its time, source (baseline, INSERT, UPDATE, DELETE), event ID, GTID, and resulting state.
Baseline location on the console endpoint
baseline_dir and baseline_s3 are accepted only by the standalone bintrail-mcp server. On the console's /mcp endpoint they are rejected for the same reason index_dsn is: an authenticated MCP client must not be able to point the console at arbitrary storage. The console uses the baseline configured for the selected server.
Access control
Pass profile on query or recover to apply a named access profile: table-level deny rules plus column redaction, authored with the CLI (bintrail flag / bintrail profile / bintrail access; profile authoring has no console UI yet). While a profile is active, Parquet archive routing is disabled (archive queries do not enforce profile rules).
Forensic attribution is a dbtrail EE capability
Tools that answer who made a change (who_changed, user_activity, connection_history) are part of dbtrail EE. They attribute events to MySQL users, hosts, and client programs. The open-source tools expose each event's raw connection_id for manual correlation.