Audit Trail

Audit Trail

Value Proposition Enforce uncompromising data governance and zero-trust compliance with automated, high-fidelity audit tracking. Capture precise pre-mutation snapshots to maintain absolute visibility into agent operations, seamlessly balancing autonomous speed with unbreakable organizational security. Read the full value proposition.

⚙️ Compliance & Governance

Ensure unwavering data governance and streamline enterprise compliance workflows with comprehensive, automated audit tracking. Ensure complete operational visibility across all AI database interactions by capturing granular pre-mutation snapshots, seamlessly bridging AI autonomy with rigorous organizational security requirements.

Zero-Contention Observability Architecture: guarantees high-throughput agent operations are never bottlenecked by forensic logging I/O.

Configure by passing the following flags during server initialization:

• --audit-log <path>: Enables the audit log and specifies the file path (e.g., --audit-log logs/mcp-audit.jsonl).
• --audit-backup: Enables pre-mutation snapshots for destructive DDL changes.
• --audit-reads: Includes read-scope tool calls (like SELECTs) in the audit log.
• --audit-redact: Automatically redacts sensitive parameters from the JSONL output.
• --audit-log-max-size: Maximum size for the audit log file. Reaching this maximum triggers automatic log rotation (default: 10MB).
• --audit-backup-data: Includes the original row data in pre-mutation snapshots (up to a configured row limit).
• --audit-backup-max-size: Maximum table size in bytes for data capture (default: 50MB).

See the Configuration guide for all audit options, including size limits and the redaction toggle.

Zero-Contention Forensic Observability: Exporter Split-Path Architecture (mysql-mcp-exporter / neverinfamous/mysql-mcp)

When running the Prometheus metrics exporter in Docker (using the local mysql-mcp-exporter build or the remote neverinfamous/mysql-mcp image), the system enforces strict read/write separation to avoid lock contention.

The primary IDE application writes continuously to mcp-audit.jsonl. The exporter container reads the IDE's audit log via a separate environment variable (AUDIT_LOG_PATH), while its internal logs are written to a distinct file (exporter-audit.jsonl):

Variable	Value	Purpose
AUDIT_LOG_PATH	/var/log/mysql-mcp/mcp-audit.jsonl	Read-only path to the IDE's live audit JSONL, mounted from your host's local log directory (e.g., ./logs or ../../logs depending on your deployment directory)

This Exporter Split-Path Architecture separates the read path (AUDIT_LOG_PATH reading mcp-audit.jsonl) from the write path (--audit-log writing to exporter-audit.jsonl for the exporter's own AuditLogger), preventing log rotation race conditions.

Observability Pipelines (Datadog & OpenTelemetry)

To integrate the audit log into centralized observability platforms:

• Datadog Agent: Configure the agent to tail mcp-audit.jsonl using inotify. Ensure the configuration points correctly to the mounted log directory and avoids duplicate autodiscovery.
• OpenTelemetry: Use the OTel Collector filelog receiver to ingest, parse, and forward the JSONL structured logs securely.

Warning

When using Grafana Alloy to forward audit logs to Loki, ensure strict routing is configured to prevent large log line truncation or buffer fragmentation.

Note

V8 isolate internal data mutations (Code Mode) are not captured by the audit log; only database queries executed from the isolate are logged.

• Resources — mysql://audit resource details
• Code Mode — Native V8 isolate
• Tools — Full tool list with scope groups
• Configuration — Configuration options