mcp-audit

A drop-in security and observability proxy for MCP servers. mcp-audit sits between an MCP client and any upstream MCP server to produce signed audit trails, redact sensitive payloads, enforce per-tool rate limits, and expose a local read-only dashboard.

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

What This Is / Is Not

mcp-audit is not a domain-specific MCP server. It is a transparent security and observability proxy that wraps any MCP server and audits the JSON-RPC traffic passing through it.

Directories may show the tools exposed by the upstream server, not tools implemented by mcp-audit itself.

Supported Transports

• stdio for local MCP clients such as Claude Desktop
• http for MCP servers exposed over HTTP

Use Cases

• Audit tool calls made by AI agents in regulated environments
• Detect unexpected or dangerous MCP tool usage
• Keep signed JSONL or SQLite logs for incident review
• Redact sensitive fields before storing requests and responses
• Apply per-tool rate limits without modifying the upstream MCP server

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.

Key	Default	Description
proxy.transport	stdio	Proxy transport: stdio or http.
proxy.upstream	required	Stdio command or HTTP upstream URL.
proxy.port	4422	HTTP listen port.
proxy.client_id	claude-desktop	Client identifier written to audit entries.
proxy.server_id	filesystem	Server identifier written to audit entries.
audit.storage	jsonl	Storage backend: jsonl or sqlite.
audit.path	./audit.jsonl	JSONL audit log path.
audit.sqlite_path	./audit.db	SQLite database path.
audit.sign	true	Enable HMAC-SHA256 signatures when a secret is set.
audit.secret	empty	HMAC secret. Prefer AUDIT_SECRET.
middleware.rate_limit.enabled	true	Enable per-client, per-tool token buckets.
middleware.rate_limit.requests_per_minute	60	Allowed requests per minute per (client_id, tool_name).
middleware.redact.enabled	true	Enable JSON key-based PII redaction.
middleware.redact.patterns	sensitive keys	Case-insensitive key fragments to redact.
dashboard.enabled	true	Serve the dashboard.
dashboard.port	9090	Dashboard listen port.

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.

Example JSONL entry:

{
  "id": "01HY8G6Y8S6W9K6ZD7VJ4Q8X4R",
  "timestamp": "2026-05-25T12:34:56Z",
  "direction": "client_to_server",
  "transport": "stdio",
  "method": "tools/call",
  "tool_name": "read_file",
  "params": {
    "name": "read_file",
    "arguments": {
      "path": "/tmp/example.txt",
      "token": "[REDACTED]"
    }
  },
  "duration_ms": 18,
  "client_id": "claude-desktop",
  "server_id": "filesystem",
  "signature": "hmac-sha256:..."
}

The signature covers:

id + timestamp + method + tool_name + raw_params

Roadmap

• Prometheus metrics
• OpenTelemetry export
• Policy engine for allow/deny rules
• SIEM-friendly exports
• Async write pipeline for high-throughput audit logging

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.