mcp-audit

A transparent Go proxy that intercepts, signs, rate-limits, redacts, and audits MCP JSON-RPC traffic without changing the client or server.

Why mcp-audit?

The MCP 2026 roadmap calls out enterprise needs around audit trails, gateway patterns, and operational visibility. mcp-audit fills that gap as a deployable sidecar or local wrapper: it sits between any MCP client and server, preserves protocol traffic, and records signed audit entries for tool calls, resource reads, prompt requests, and all other JSON-RPC methods.

+-------------+    JSON-RPC / MCP     +-----------+      JSON-RPC / MCP     +-------------+
| MCP client  | <-------------------> | mcp-audit | <---------------------> | MCP server  |
+-------------+                       +-----------+                         +-------------+
                                            |
                                            v
                                JSONL or SQLite audit log
                                            |
                                            v
                                   Read-only dashboard

Demo

Quick Start

Install Go, then build from source:

brew install go
go install github.com/P4ST4S/mcp-audit/cmd/mcp-audit@v0.2.0

Run in stdio mode:

AUDIT_SECRET="$(openssl rand -hex 32)" \
mcp-audit --transport stdio --upstream "npx @modelcontextprotocol/server-filesystem /tmp"

Run in HTTP mode:

mcp-audit --transport http --upstream http://localhost:8080 --port 4422

Run with Docker Compose:

docker compose up --build

The dashboard is available at http://localhost:9090 by default.

Configuration

mcp-audit loads config.yaml from the current directory by default. CLI flags override config values, and AUDIT_SECRET overrides audit.secret.

CLI flags:

--transport    stdio | http
--upstream     upstream server command or URL
--port         proxy port for http mode
--config       path to config.yaml
--storage      jsonl | sqlite
--no-dashboard disable the web dashboard
--log-level    debug | info | warn | error

Claude Desktop

Configure Claude Desktop to spawn mcp-audit instead of the upstream MCP server:

{
  "mcpServers": {
    "filesystem-audited": {
      "command": "mcp-audit",
      "args": [
        "--transport",
        "stdio",
        "--upstream",
        "npx @modelcontextprotocol/server-filesystem /tmp"
      ],
      "env": {
        "AUDIT_SECRET": "replace-with-a-long-random-secret"
      }
    }
  }
}

Dashboard

The dashboard shows recent entries, filters, expandable request/result JSON, top tools, calls today, and error rate. It refreshes every five seconds.

Audit Entries

Each stored entry includes a ULID, timestamp, direction, transport, JSON-RPC method, tool name when present, redacted params/result, JSON-RPC error when present, duration, client/server identifiers, and an optional HMAC-SHA256 signature.

The signature covers:

id + timestamp + method + tool_name + raw_params

Contributing

This project is experimental. Keep changes small, run go build ./... and go vet ./..., and prefer standard library behavior over new dependencies.

See CONTRIBUTING.md for setup, PR expectations, and project principles. See CHANGELOG.md for release history.

License

Apache-2.0. See LICENSE.