MCP Server

audit-mcp is a Go binary that speaks the Model Context Protocol. Once wired into your AI host (Claude Code, Claude Desktop, Cursor), you can ask the audit log questions conversationally:

"Show me every change to order #42 in the last 24 hours."

"What did user 17 look like at 09:00 yesterday?"

"Give me the full transaction view for 20260413T...."

Behind the scenes, the AI calls one of five tools the server exposes, the server queries your audit DB, and the AI summarizes the result.

Read-only by design

The server never issues INSERT, UPDATE, DELETE, or ALTER. Exposed tool surface is strictly read:

• auditor.Query
• auditor.API().Query
• auditor.QueryByTransaction
• auditor.Snapshot

Purge and Restore are intentionally not exposed. Destructive operations belong in your app's own admin tooling, not in an AI tool surface.

For maximum safety, point the server at a database user with SELECT-only privileges on the two audit tables.

Tools

All row-returning tools cap at 500 rows to keep responses within the AI's context window.

Install

# Installs as the binary `mcp` (Go uses the module directory name).
go install github.com/gopackx/go-audit/mcp@latest

# Optional: rename for clarity.
mv "$(go env GOBIN)/mcp" "$(go env GOBIN)/audit-mcp"

The binary embeds pure-Go drivers for PostgreSQL (pgx), MySQL, and SQLite (modernc.org/sqlite) — no cgo, no native libs needed.

Configure

Configuration is via environment variables:

DSN examples:

# PostgreSQL (pgx)
postgres://audit_reader:secret@db.internal:5432/myapp?sslmode=require

# MySQL
audit_reader:secret@tcp(db.internal:3306)/myapp?parseTime=true

# SQLite
file:/var/lib/myapp/audit.db?mode=ro

Wire into Claude Code

Add to ~/.claude/mcp.json (user-scoped) or .mcp.json in your project root (team-scoped):

{
  "mcpServers": {
    "go-audit": {
      "command": "audit-mcp",
      "env": {
        "GOAUDIT_DIALECT": "postgres",
        "GOAUDIT_DSN": "postgres://audit_reader:secret@db.internal:5432/myapp?sslmode=require"
      }
    }
  }
}

Restart Claude Code. The five tools above appear in tool listings and the AI will reach for them when you ask about audit history.

Wire into Claude Desktop

Same JSON shape. In the Desktop app, open Settings → MCP → Edit Config and paste the mcpServers block.

Wire into Cursor

Cursor reads ~/.cursor/mcp.json with the same schema.

Smoke test

Confirm the binary handshakes properly without touching a real production DB by pointing it at an in-memory SQLite:

GOAUDIT_DIALECT=sqlite GOAUDIT_DSN=":memory:" audit-mcp <<EOF
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
EOF

You should see two JSON-RPC response lines on stdout, the second listing all five tools.

Versioning

Tagged independently from the core library: mcp/v1.1.0, mcp/v1.2.0, etc. Install a specific version:

go install github.com/gopackx/go-audit/mcp@v1.1.0

Limitations

• Stdio transport only. HTTP/SSE transport isn't wired up — all three target AI hosts use stdio anyway, but if you need remote-deploy MCP, you'll need to wrap the binary.
• Read-only. As stated above, deliberate. Open an issue if your workflow needs scoped write access — there are well-known patterns for safe AI-driven writes, but we want to think through them before exposing them.
• No automatic dialect detection. The server requires GOAUDIT_DIALECT to be set explicitly, same as the core library.