SQL Audit MCP Server for AI Agents

DeltaScope is an offline-first SQL audit MCP server that lets AI agents review MySQL, TiDB, and PostgreSQL DDL and DML statements before they reach a database. It runs as a stdio MCP server, exposing an audit_sql tool that AI coding agents call inline during development sessions.

How it works

When an AI agent generates or encounters a SQL statement, it calls DeltaScope's audit_sql MCP tool. DeltaScope parses the SQL, evaluates every applicable rule, and returns structured findings with blockers, warnings, and notices. No database connection is required for offline audit. An optional metadata-aware mode uses read-only table statistics to enrich findings.

// AI agent calls the MCP tool
audit_sql({
  sql: "ALTER TABLE users DROP COLUMN email;",
  dialect: "mysql"
})

// DeltaScope returns structured findings
{
  verdict: "reject",
  summary: { blockers: 1, warnings: 0, notices: 0 },
  statements: [{
    findings: [{
      severity: "blocker",
      rule: "ddl.alter.drop.column",
      message: "dropping column \"email\" is a destructive change"
    }]
  }]
}

One-click setup

# Add to Claude Code
claude mcp add --scope user deltascope -- npx -y @fanduzi/deltascope-mcp

# Add to Codex
codex mcp add deltascope -- npx -y @fanduzi/deltascope-mcp

The npm launcher automatically downloads and runs the correct deltascope-mcp binary for your platform. No manual binary install required.

MCP tools exposed

audit_sql — audit one or more SQL statements (offline or metadata-aware)
describe_rule — get details and examples for a specific rule
list_rules — list all available audit rules
get_capabilities — query dialect support, error codes, and connection options

Metadata-aware audit via MCP

For richer findings, provide a connection so DeltaScope can read table statistics. Named connections support connect_timeout:

# ~/.config/deltascope/connections.yaml
connections:
  local_mysql:
    host: 127.0.0.1
    port: 3306
    user: root
    password_env: MYSQL_PASSWORD
    schema: app
    dialect: mysql
    connect_timeout: 5s

MySQL, TiDB, and PostgreSQL all support metadata-aware audit with connect timeout control.

Runtime config for the MCP server

deltascope-mcp -runtime-config /etc/deltascope/runtime.yaml

Runtime config sets logging defaults and metadata connect timeout. It does not change audit rules. See runtime-config.yaml for the full example.

Supported databases

MySQL — DDL and DML audit with dialect-specific rules
TiDB — use dialect: "tidb" for TiDB-specific parsing
PostgreSQL — DDL and DML audit including constraints and DCL patterns

MySQL DDL Audit Tool → PostgreSQL DDL Audit Tool → SQL Migration Risk Checker → TiDB Schema Change Audit →

What DeltaScope is not

Not a database proxy or runtime query firewall. DeltaScope reviews static SQL text before execution.
Not a migration execution engine. It does not run or apply migrations.
Not a live privilege or role validation system. It checks SQL patterns, not runtime permissions.

Frequently asked questions

Which AI agents can use the MCP server?

Any MCP-compatible agent works: Claude Code, Codex, Cursor, Windsurf, and other tools that support the Model Context Protocol. The server runs as a stdio process.

Does the MCP server need a database connection?

No. The default mode is offline-first. It parses SQL text and evaluates rules without any network connection. An optional metadata-aware mode can use read-only table statistics if you provide connection details.

Can I customize audit rules?

Yes. Every rule has a configurable severity level (blocker, warning, notice) and optional parameters. Configure via a YAML policy file.

How does connect_timeout work?

Set connect_timeout in a named connection YAML or pass it in a direct connection input. It controls how long the metadata connection waits before timing out. Runtime config can set a process-wide default; request-level values override it.