Tools Reference
Complete reference for the tools available to Claude via the bintrail-mcp server
All tools are annotated ReadOnlyHint and IdempotentHint, read the index,
and never touch the source database.
Web interface /mcp (setup) | Standalone bintrail-mcp | |
|---|---|---|
| Connection | The web interface owns it; index_dsn rejected | BINTRAIL_INDEX_DSN or per-call index_dsn |
| Server | /mcp default, /mcp/{name} one server | One DSN per call |
profile | Rejected | Accepted |
baseline_dir / baseline_s3 | Rejected; uses the server's backup | Accepted, or BINTRAIL_BASELINE_DIR / _S3 |
| Limits | Web interface result caps | Env-tunable query ceiling, recover uncapped |
Transport and flags: MCP server reference.
Times accept YYYY-MM-DD HH:MM:SS or RFC 3339. Composite keys are
pipe-delimited: 123|2.
query
Search indexed changes. Returns before and after images, timestamps, metadata; merges live index and Parquet archives.
| Parameter | Notes |
|---|---|
schema, table | |
pk / pks | One key or several (pks needs schema and table; exclusive with pk) |
pk_min, pk_max | Integer range, one integer key column only; pair with since/until |
limit_per_pk | Latest N events per key; needs pk or pks |
event_type | INSERT, UPDATE, DELETE |
gtid | e.g. uuid:42 |
since, until | |
changed_column | UPDATEs that modified this column |
query_hash | Every execution of one statement shape; not on surfaces that withhold statement text |
column_eq | Array of column=value, AND-ed; literal NULL matches JSON null |
flag | Tables or columns carrying this flag |
format | json (default), table, csv |
limit | Default 100 |
order | ASC (default, keeps oldest) or DESC (keeps newest; use for "last N") |
profile | Standalone only |
no_archive | Skip Parquet archives |
recover
Reversal SQL, dry-run only: BEGIN/COMMIT, newest change first. DELETE →
INSERT, UPDATE → reverse UPDATE, INSERT → DELETE.
Parameters: the query filters except changed_column, query_hash,
format and order (reversing a filtered subset of a row's history could
produce a state that never existed). limit defaults to 1000.
| Transport parameter | Notes |
|---|---|
summary_only | Statement count and script size, no SQL |
sql_offset, sql_limit | Fetch a large script in statement-aligned chunks that concatenate into the exact script |
A script over the response size limit is not returned whole: the result is a JSON summary with the statement count and how to page it.
recover_cascade
Reversal SQL for rows changed by a foreign-key ON DELETE / ON UPDATE
CASCADE or SET NULL, which InnoDB applies below the binlog. Dry-run only.
| Parameter | Notes |
|---|---|
schema, table | Parent table (required) |
pk / pks | Changed parent keys; exclusive |
since, until | Parent changes in the window |
lookback | How far back to search child state (default 30d) |
max_depth | Parent → child → grandchild (default 5) |
limit | Parent events, applied separately to DELETE and UPDATE scans (default 1000) |
allow_incomplete | Return a provably partial script instead of failing |
baseline_dir, baseline_s3 | Standalone: enables the backup fallback |
summary_only, sql_offset, sql_limit | Same as recover |
Result: SQL plus counts (parents, children re-inserted, SET NULL and key
restores), incomplete (why it is partial), warnings, and complete
(incomplete is empty).
status
Indexed binlog files, partition layout with estimated row counts, event
summary. No parameters besides index_dsn (standalone).
list_schema_changes
CREATE, CREATE OR REPLACE, ALTER, DROP, RENAME, TRUNCATE with statement, time, binlog
file, position, GTID and covering snapshot_id (null = no snapshot after it).
Newest first; same-second changes by binlog file and position.
| Parameter | Notes |
|---|---|
schema, table, since, until | |
ddl_type | Prefix match, e.g. ALTER. CREATE also matches MariaDB's CREATE OR REPLACE TABLE; CREATE TABLE does not |
limit | Default 100 |
uncovered_only | Only changes with no covering snapshot, excluding TRUNCATE |
Same history in the web interface: Investigate → Schema changes.
reconstruct
One row's full state at a moment: backup plus the events after it, so columns never touched in the window still resolve. Needs a backup.
| Parameter | Notes |
|---|---|
schema, table, pk | Required |
at | Default now |
history | Every state transition from the backup to at |
allow_gaps | Proceed over missing history; what was overridden comes back in warnings |
baseline_dir, baseline_s3 | Standalone only |
Result: state, baseline_time, event_count, and the three outcomes: the
state, deleted: true, or found: false (no backup row for that key).
Access control
profile on query or recover (standalone) applies table denies and column
redaction, authored in Settings → Access profiles or with bintrail flag /
bintrail profile / bintrail access. An active profile disables archive
routing.