db-mcp includes a built-in JSONL audit trail with per-call token estimates, OAuth identity, timing, and outcome. Write/admin tools are always logged; read-scoped tools can be opted in via --audit-reads. Size-based log rotation prevents unbounded growth.

CLI flags:

node dist/cli.js --audit-log /var/log/audit.jsonl --sqlite-native ./database.db

# Omit tool arguments from entries
node dist/cli.js --audit-log /var/log/audit.jsonl --audit-no-redact --sqlite-native ./database.db

Environment variables:

Docker:

docker run --rm -p 3000:3000 \
  -v ./data:/app/data \
  writenotenow/db-mcp:latest \
  --transport http --port 3000 --server-host 0.0.0.0 \
  --audit-log /var/log/audit.jsonl \
  --sqlite-native /app/data/database.db

For Docker, Kubernetes, and orchestrated environments, route audit entries directly to the container log stream:

--audit-log stderr
# or
AUDIT_LOG=stderr

The orchestrator (Docker log driver, Kubernetes Fluentd/Fluentbit, CloudWatch Logs, etc.) captures stderr natively — no volume mounts or log rotation needed.

Each line is a self-contained JSON object:

{
  "timestamp": "2026-05-30T12:00:00.000Z",
  "requestId": "75e9f60f-aad0-4519-81db-e0a79a57dd0e",
  "tool": "sqlite_write_query",
  "category": "write",
  "scope": "write",
  "user": "jane@example.com",
  "scopes": ["read", "write"],
  "durationMs": 3,
  "success": true,
  "args": {},
  "tokenEstimate": 42
}

Write and admin tools are always logged. Read-scoped tools are logged only when --audit-reads (or AUDIT_READS=true) is enabled.

Read entries are compact — args, user, and scopes are omitted to keep per-entry size small.

The sqlite://audit resource exposes recent audit entries with a session summary to AI agents:

{
  "summary": {
    "totalTokenEstimate": 14200,
    "callCount": 47,
    "topToolsByTokens": [
      { "tool": "sqlite_read_query", "calls": 12, "tokens": 8400 },
      { "tool": "sqlite_execute_code", "calls": 3, "tokens": 3100 }
    ],
    "note": "Last 47 tool calls consumed ~14,200 tokens"
  },
  "entries": [{ "tool": "sqlite_read_query", "tokenEstimate": 420, "..." }],
  "total": 47
}

The summary block gives agents session-level token consumption visibility. When audit logging is disabled, the resource returns an empty array with a status message.

The audit log rotates automatically when it exceeds the configured max size (default: 10MB). On rotation, the current file cascades down a 5-tiered rotation chain (.1 through .5). The oldest archive is deleted when a new rotation occurs.

For container deployments using --audit-log stderr, rotation is unnecessary — the orchestrator handles log management.

Pre-mutation DDL snapshots automatically capture the state of database objects before destructive operations. This enables point-in-time recovery and schema drift detection.

# Enable audit log + backup snapshots
node dist/cli.js --audit-log /var/log/audit.jsonl --audit-backup --sqlite-native ./database.db

# Also capture sample data
node dist/cli.js --audit-log /var/log/audit.jsonl --audit-backup --audit-backup-data --sqlite-native ./database.db

Snapshots are triggered by destructive tools:

Five MCP tools provide agent access to backup snapshots:

Snapshots are cleaned up automatically based on age and count limits. The oldest snapshots exceeding either limit are deleted first.

JSONL format is compatible with standard log aggregation platforms:

For container deployments, --audit-log stderr is the recommended approach.

When OAuth is enabled with audit logging, write/admin audit entries capture the authenticated user (claims.sub) and granted scopes — providing a forensic trail linking mutations to identities.

• OAuth & Security — Scope definitions and access control
• Resources & Prompts — sqlite://audit resource
• Code Mode — Admin scope requirements
• Tool Reference — Full tool list with scope groups