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 allow/deny policies and per-tool rate limits, and expose a local read-only dashboard.

For a contributor-oriented map of the runtime, package boundaries, concurrency model, and design invariants, see ARCHITECTURE.md.

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

HTTP upstreams can use custom CA bundles, TLS server name overrides, and optional mTLS client certificates. Upstream retries are disabled by default and only apply to conservative, idempotent JSON-RPC methods when enabled; tools/call is not retried.

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
• Block disallowed tools and apply per-tool rate limits without modifying the upstream MCP server

Demo

Install

Download a prebuilt binary from GitHub Releases. Prebuilt archives are published for Linux (amd64, arm64), macOS (amd64, arm64), and Windows (amd64). Pick the archive that matches your OS and CPU architecture.

Prerequisites

• No runtime dependency for mcp-audit itself (statically linked, CGO_ENABLED=0).
• The stdio examples below launch an upstream MCP server via npx, which requires Node.js 18+ on PATH. This is only needed for the example upstream, not for mcp-audit.
• Windows binaries are published for amd64 only. There is no windows_arm64 build; on Windows on ARM, run the amd64 binary under emulation or build from source with go build ./cmd/mcp-audit.

Linux

curl -L -o mcp-audit.tar.gz \
  https://github.com/P4ST4S/mcp-audit/releases/download/v0.9.0/mcp-audit_0.9.0_linux_amd64.tar.gz
curl -L -o mcp-audit_checksums.txt \
  https://github.com/P4ST4S/mcp-audit/releases/download/v0.9.0/mcp-audit_0.9.0_checksums.txt
sha256sum -c mcp-audit_checksums.txt --ignore-missing
tar -xzf mcp-audit.tar.gz
./mcp-audit --version

On 64-bit ARM Linux, replace linux_amd64 with linux_arm64.

Install it on your PATH (system-wide):

sudo install -m 0755 mcp-audit /usr/local/bin/mcp-audit
mcp-audit --version

macOS

macOS ships shasum instead of sha256sum. Use darwin_arm64 for Apple Silicon (M1/M2/M3) and darwin_amd64 for Intel Macs.

curl -L -o mcp-audit.tar.gz \
  https://github.com/P4ST4S/mcp-audit/releases/download/v0.9.0/mcp-audit_0.9.0_darwin_arm64.tar.gz
curl -L -o mcp-audit_checksums.txt \
  https://github.com/P4ST4S/mcp-audit/releases/download/v0.9.0/mcp-audit_0.9.0_checksums.txt
shasum -a 256 -c mcp-audit_checksums.txt --ignore-missing
tar -xzf mcp-audit.tar.gz
./mcp-audit --version

macOS Gatekeeper may quarantine the downloaded binary. If it is blocked, clear the quarantine attribute:

xattr -d com.apple.quarantine ./mcp-audit

Install it on your PATH:

sudo install -m 0755 mcp-audit /usr/local/bin/mcp-audit
mcp-audit --version

Windows

Windows builds are published as a .zip archive containing mcp-audit.exe. The following uses PowerShell:

Invoke-WebRequest -Uri "https://github.com/P4ST4S/mcp-audit/releases/download/v0.9.0/mcp-audit_0.9.0_windows_amd64.zip" -OutFile "mcp-audit.zip"
Invoke-WebRequest -Uri "https://github.com/P4ST4S/mcp-audit/releases/download/v0.9.0/mcp-audit_0.9.0_checksums.txt" -OutFile "mcp-audit_checksums.txt"

# Verify the checksum and fail if it does not match
$expected = ((Select-String -Path mcp-audit_checksums.txt -Pattern "windows_amd64.zip").Line -split '\s+')[0].ToLower()
$actual   = (Get-FileHash -Algorithm SHA256 mcp-audit.zip).Hash.ToLower()
if ($actual -ne $expected) { throw "Checksum mismatch: expected $expected, got $actual" }

Expand-Archive -Path mcp-audit.zip -DestinationPath . -Force
.\mcp-audit.exe --version

To make mcp-audit available in every new terminal, move mcp-audit.exe to a directory on your PATH (for example a per-user tools folder), then add it to the user PATH:

$dest = "$env:LOCALAPPDATA\Programs\mcp-audit"
New-Item -ItemType Directory -Force -Path $dest | Out-Null
Move-Item -Force .\mcp-audit.exe "$dest\mcp-audit.exe"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$dest", "User")
# Open a new terminal, then:
mcp-audit --version

Run with Docker:

docker run --rm ghcr.io/p4st4s/mcp-audit:v0.9.0 --version

Or install with Go:

go install github.com/P4ST4S/mcp-audit/cmd/[email protected]

Quick Start

Run in stdio mode:

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

On Windows PowerShell, generate the secret and set it as an environment variable:

$env:AUDIT_SECRET = -join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) })
.\mcp-audit.exe --transport stdio --upstream "npx @modelcontextprotocol/server-filesystem C:\Temp"

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.
Prometheus metrics are available at http://localhost:9091/metrics by default.

Examples

• Cursor stdio configuration
• Continue stdio configuration

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
--upstream-timeout upstream HTTP request timeout in milliseconds
--config       path to config.yaml
--storage      jsonl | sqlite
--no-dashboard disable the web dashboard
--no-metrics   disable Prometheus metrics
--version      print version and exit
--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.

Prometheus Metrics

mcp-audit exposes Prometheus metrics on a separate endpoint so platform teams can scrape operational data without exposing the dashboard.

scrape_configs:
  - job_name: mcp-audit
    static_configs:
      - targets: ["localhost:9091"]

Application metrics use the mcp_audit_ prefix and avoid unbounded labels. Tool-level labels can be disabled with metrics.tool_labels: false for stricter cardinality control. Policy decisions are exposed as mcp_audit_policy_decisions_total{action="allow|deny"}.

For a ready-made Prometheus + Grafana stack, see examples/docker-compose-observability.

Policy Engine

mcp-audit can enforce synchronous allow/deny rules before a tools/call reaches the upstream MCP server. Denied calls return a JSON-RPC error and are still written to the audit log.

policy:
  enabled: true
  default_action: allow
  rules:
    - action: deny
      client_id: claude-desktop
      server_id: filesystem
      tool_name: delete_file
      reason: "Destructive filesystem operations are blocked"

Rules are evaluated in order. Empty fields and * match any value, so default_action: deny can be used with explicit allow rules for stricter deployments.

OpenTelemetry

mcp-audit can export tools/call audit entries as OTLP/HTTP JSON spans to Jaeger, Tempo, Honeycomb, or any OTLP-compatible collector.

otel:
  enabled: true
  endpoint: "http://localhost:4318"
  service_name: "mcp-audit"
  headers:
    Authorization: "Bearer your-token"
  timeout_ms: 5000
  retry:
    max_retries: 3
    initial_interval_ms: 200
    max_interval_ms: 2000

The exporter uses current OpenTelemetry MCP and GenAI semantic conventions where possible, including mcp.method.name, jsonrpc.request.id, gen_ai.operation.name, gen_ai.tool.name, network.transport, network.protocol.name, rpc.response.status_code, and error.type. Project-specific attributes are kept link-oriented, such as mcp_audit.entry_id, mcp_audit.direction, mcp_audit.client_id, mcp_audit.server_id, mcp_audit.storage, and mcp_audit.signature.present.

Request params and tool results are not exported to spans by default. The signed JSONL or SQLite audit row remains the evidence artifact; OTLP provides correlation, latency, and operational visibility.

Exporter health is visible through Prometheus metrics under the mcp_audit_otel_ prefix, including export requests, span outcomes, dropped spans, queue depth, and queue capacity. Temporary OTLP failures are retried with bounded exponential backoff; Retry-After is honored for retryable responses up to otel.retry.max_interval_ms.

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

• SIEM-friendly exports
• OTLP compression and trace context propagation

Contributing

Keep changes small, run go build ./... and go vet ./..., and prefer standard library behavior over new dependencies. Stability guarantees are documented in STABILITY.md.

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

Community

• Discussions: questions, ideas, and design conversations
• Issues: bug reports and concrete feature requests
• Security: see SECURITY.md for the private vulnerability reporting process

License

Apache-2.0. See LICENSE.