Tools Reference

The following tools are available to Claude and other AI assistants connected to dbtrail.

list_servers

List all registered MySQL servers for the current tenant.

Parameters

None required.

Response

Returns a list of servers, each containing:

• id — server UUID (use as server_id in other tools)
• name — human-readable server name
• host — MySQL hostname
• port — MySQL port
• status — current server status (pending, active, disconnected, etc.)

list_tables

List schemas and tables that have indexed binlog data on a server. Call this before query or recover to discover valid schema and table names.

Parameters

Response

Returns a list of schema/table pairs that have indexed change data:

• server_id — UUID of the queried server
• tables — array of {"schema": "...", "table": "..."} objects

query

Search indexed binlog changes by schema, table, time range, or event type.

Parameters

Response

Returns:

• success — whether the operation succeeded
• total_count — the true total number of matching events (regardless of limit)
• has_more — whether there are more events beyond the limit
• events — list of change events (capped by limit), each containing:
  • event_type — INSERT, UPDATE, or DELETE
  • timestamp — when the change occurred
  • schema / table — where the change happened
  • primary_key — primary key of the affected row (as an object)
  • before — row state before the change (null for INSERTs)
  • after — row state after the change (null for DELETEs)

count_events

Count indexed binlog change events with optional grouping. Returns aggregate counts without transferring row data — much more efficient than query for answering volume questions.

Parameters

Response

Returns:

• success — whether the operation succeeded
• total — sum of all event counts
• groups — array of count groups (sorted by count descending), each containing:
  • schema — schema name (present when grouped by schema)
  • table — table name (present when grouped by table)
  • event_type — event type (present when grouped by event_type)
  • count — number of matching events

Example

With group_by: ["schema", "table"] and event_type: "INSERT":

{
  "success": true,
  "groups": [
    { "schema": "demo", "table": "metrics", "count": 12440 },
    { "schema": "demo", "table": "order_items", "count": 8910 },
    { "schema": "demo", "table": "audit_log", "count": 4823 },
    { "schema": "demo", "table": "orders", "count": 3022 }
  ],
  "total": 29195
}

recover

Generate SQL statements to reverse database changes. Always runs in dry-run mode — the SQL is generated but never executed.

Recovery is FK-aware by default — if a parent row referenced by a foreign key was also deleted, it is automatically included in the recovery SQL in the correct dependency order.

Parameters

Response

Returns:

• success — whether the operation succeeded
• sql — the recovery SQL (wrapped in a transaction, topologically sorted for FK correctness)
• affected_rows — number of rows affected
• operations — list of individual recovery operations
• recovery_steps — (when FK resolution is active) ordered list of steps, each with a reason explaining why it was included
• warnings — notes about skipped tables, depth limits reached, or circular dependencies detected

Recovery logic

FK resolution

When resolve_fk is enabled (the default), recover automatically:

• Walks up the FK chain to find deleted parent rows that must be restored first (up to 5 levels deep)
• Walks down the FK chain when include_dependents: true to include deleted child rows
• Topologically sorts all statements so parents are inserted before children
• Wraps with SET FOREIGN_KEY_CHECKS=0/1 when circular or self-referencing FKs are detected
• Deeper FK chains are skipped with a warning

status

Get streaming status for a server — replication lag, binlog position, events indexed, and disk usage.

Parameters

Response

Returns server and stream health details including:

• server_id — UUID of the server
• Replication position, lag, and event counts

forensics_capabilities

Check what forensic data sources are available on a MySQL server — whether performance_schema is enabled, which consumers are active for statement history, and whether an audit log plugin is installed.

Parameters

Response

Returns performance_schema status (enabled, consumers, thread accessibility) and audit_log status (installed, plugin name, variant, config).

who_changed

Trace who modified a specific row. Queries binlog events for the given table and primary key to show what changed and when, with forensic enrichment (user/host attribution) when available from performance_schema.

Parameters

Response

Returns binlog change events with forensic metadata (user, host, program) when available.

user_activity

Show all recent activity by a specific MySQL user. Queries performance_schema.events_statements_history_long for recent SQL statements including query text, duration, rows affected, and connection details.

Parameters

Response

Returns recent SQL statements with query text, duration, and rows affected. When performance_schema is unavailable, returns fallback SQL queries.

connection_history

Show connections from a specific MySQL user or host/IP. Returns current active connections with user, host, database, command state, and running query.

Parameters

Response

Returns matching connections with metadata. When performance_schema is unavailable, returns fallback SQL queries.

Access rules

Several tools enforce access rules:

• query / batch_query — strips unauthorized columns from before/after images and removes forensic SQL text when columns are restricted
• count_events — enforces table-level access when a specific schema and table are targeted
• who_changed — enforces table-level access and removes forensic SQL text when columns are restricted
• recover — enforces table-level access and removes forensic SQL text when columns are restricted

If the connected user's role has no access to the queried table, the tool returns an error.

Permissions

All tools require the mcp:connect permission, which is available to analysts, operators, admins, and owners. Viewers do not have access to these tools.