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

Related MCP server: GitHub MCP Server Plus

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

For detailed platform-specific instructions and troubleshooting, see INSTALL.md.

The current release is v1.3.0. See the changelog and migration guide before upgrading.

Download the latest prebuilt binary and run:

# Linux/macOS: resolve latest, download, verify it starts
version=$(curl -fsSL https://api.github.com/repos/P4ST4S/mcp-audit/releases/latest \
  | grep '"tag_name"' | head -n1 | cut -d'"' -f4 | sed 's/^v//')
os=$(uname | tr '[:upper:]' '[:lower:]')
arch=$(uname -m); [ "$arch" = "x86_64" ] && arch=amd64 || arch=arm64
base="https://github.com/P4ST4S/mcp-audit/releases/download/v${version}"
archive="mcp-audit_${version}_${os}_${arch}.tar.gz"
curl -L -o "${archive}" "${base}/${archive}"
tar -xzf "${archive}"
./mcp-audit --version

Run with Docker:

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

Install from source with Go:

go install github.com/P4ST4S/mcp-audit/cmd/mcp-audit@latest

To pin a specific release for reproducible installs, see INSTALL.md.

Quick Start

Run in stdio mode:

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

For the native Windows binary, use HTTP mode. Stdio upstreams require /bin/sh; run the stdio examples inside WSL. On Windows PowerShell:

$env:MCP_AUDIT_SIGNING_SECRET = -join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) })
.\mcp-audit.exe --transport http --upstream http://localhost:8080 --port 4422

Run in HTTP mode:

MCP_AUDIT_SIGNING_SECRET="$(openssl rand -hex 32)" \
mcp-audit --transport http --upstream http://localhost:8080 --port 4422

Run with Docker Compose:

export MCP_AUDIT_SIGNING_SECRET="$(openssl rand -hex 32)"
docker compose -f examples/docker-compose-observability/docker-compose.yml up --build

The dashboard is available at http://127.0.0.1:9090 by default. Prometheus metrics are available at http://localhost:9091/metrics by default.

Examples

• Cursor stdio configuration

• Continue stdio configuration

• VS Code stdio configuration

• Claude Desktop stdio configuration

• Zed stdio configuration

Configuration

mcp-audit loads config.yaml from the current directory by default. CLI flags override config values. MCP_AUDIT_SIGNING_SECRET overrides audit.secret; the legacy AUDIT_SECRET name remains supported at lower precedence.

Upgrading an existing deployment? Follow the v1.2 migration guide before changing production configuration.

For Streamable HTTP clients, the proxy forwards MCP session, cache, and multi-round-trip metadata unchanged. When Mcp-Method, Mcp-Name, or Mcp-Protocol-Version are present, they are validated against the JSON-RPC body before forwarding. A mismatch returns HTTP 400 with JSON-RPC code -32600.

By default, mcp-audit strips hop-by-hop request headers and Authorization before forwarding HTTP requests to the upstream. To pass a bearer token to a trusted authenticated upstream, opt in explicitly:

proxy:
  forward_headers:
    - Authorization

Security note: forwarded headers, including secrets like bearer tokens, are transmitted verbatim to the upstream server. Only enable this if you control or trust the upstream MCP server. Authorization is the only sensitive header that can be opt-in forwarded because some MCP HTTP servers require it for upstream authentication. Cookie, Set-Cookie, and Proxy-Authorization are always rejected: they represent state destined for other components such as browser sessions or proxy chains and have no legitimate use in MCP request forwarding. If an existing deployment relied on implicit Authorization forwarding, add the config above.

HTTP authentication

HTTP mode can use an explicitly configured local identity, a pre-shared bearer token, or an OIDC access token. For a simple authenticated deployment, keep the token outside the YAML file:

export MCP_AUDIT_STATIC_BEARER_TOKEN="$(openssl rand -hex 32)"

auth:
  mode: static_bearer
  static:
    subject: automation
    client_id: ci-client
    issuer: static
    roles: [operator]
    scopes: [mcp:read]

OIDC mode validates the JWT signature, exact issuer and audience, expiry, and not-before claims using an asymmetric algorithm allowlist and rotating JWKS:

auth:
  mode: oidc
  oidc:
    issuer: https://login.example.com/tenant
    audience: mcp-audit
    jwks_uri: https://login.example.com/tenant/.well-known/jwks.json
    allowed_methods: [RS256]

The inbound Authorization header is stripped before upstream forwarding by default. proxy.forward_headers: [Authorization] is a separate, explicit trust decision for an upstream that also requires that credential.

Incoming TLS

To terminate TLS at the proxy, configure both the certificate chain and private key. Incoming TLS uses TLS 1.2 or newer:

proxy:
  tls:
    enabled: true
    cert_file: /etc/mcp-audit/tls.crt
    key_file: /etc/mcp-audit/tls.key

The other proxy.tls.* settings continue to control the outbound connection to an HTTPS upstream MCP server.

JSONL rotation is disabled by default and supports size-based and UTC time-based triggers. Rotated archives use UTC timestamps such as audit.jsonl.20260610T214605Z; if multiple rotations happen in the same second, numeric suffixes are added. The archive timestamp reflects the wall-clock time of the rotation event, not the cutoff that was crossed. Time-based rotation is append-driven: mcp-audit does not start a background timer, so if no writes occur for several days, the active file is not rotated until the next append after the cutoff. Missed cutoffs are not caught up; the next append creates at most one archive.

audit:
  storage: jsonl
  rotation:
    max_size_bytes: 104857600
    interval: daily
    max_files: 10
    max_age_days: 30

max_age_days uses the rotation timestamp encoded in the archive filename. This means age since rotation, not the age of the oldest entry inside the archive. Age retention runs before max_files retention. Compression and SQLite archival are not part of this release.

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

Verify audit evidence

Verify every Integrity v2 or legacy signature in a JSONL or SQLite audit artifact:

MCP_AUDIT_SIGNING_SECRET="your-signing-secret" mcp-audit verify audit.jsonl
MCP_AUDIT_SIGNING_SECRET="your-signing-secret" mcp-audit verify audit.db --json

The verifier detects JSONL and SQLite automatically. Use --format jsonl or --format sqlite to override detection, and --key-id ID when the Integrity v2 records were produced with a non-default key ID. AUDIT_SECRET remains a compatible fallback for existing deployments.

Text output reports verified, invalid, legacy, and unsigned record counts. Exit status 0 means every record has a valid Integrity v2 or legacy signature, 1 means at least one record is invalid or unsigned, and 2 means the command or artifact could not be read. --json emits the same result with the total count and first verification error for automation.

For v2-only evidence, use mcp-audit verify audit.jsonl --require-integrity-v2. This rejects legacy-only entries and empty artifacts. The default command keeps legacy compatibility; individual signatures alone do not prove completeness.

To detect deleted, duplicated, or reordered entries in a closed snapshot:

mcp-audit checkpoint audit.jsonl --output audit.checkpoint.json
# Store this expected checkpoint separately, with controlled access.
mcp-audit verify audit.jsonl --checkpoint /trusted/audit.checkpoint.json

Both commands use MCP_AUDIT_SIGNING_SECRET (or legacy AUDIT_SECRET) and accept --key-id. A checkpoint requires nonempty, valid Integrity v2 evidence; verification implicitly requires v2. The same commands work with SQLite. See the v1.3 migration guide for storage, backup, and trust requirements.

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": {
        "MCP_AUDIT_SIGNING_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.

By default the dashboard listens only on 127.0.0.1:9090. To expose it on another interface, configure dashboard.bind_address explicitly and enable authentication or place it behind a trusted access proxy.

dashboard:
  enabled: true
  bind_address: 127.0.0.1
  port: 9090
  auth:
    token: "replace-with-a-long-random-token"

When dashboard.auth.token is configured, requests to /, /api/entries, and /api/stats must include:

Authorization: Bearer replace-with-a-long-random-token

Missing or invalid credentials return 401 Unauthorized with WWW-Authenticate: Bearer realm="mcp-audit-dashboard". Repeated failed authentication attempts from the same remote address are throttled with 429 Too Many Requests.

Dashboard JSON API responses include Cache-Control: no-store so intermediaries and browsers do not retain audit payloads.

Dashboard statistics cover all retained entries (including rotated JSONL files), not just the newest 10,000. Terminal operations count once in either transport direction; legacy entries count on the client-to-server side. total_today uses the proxy's local calendar day, while error_rate and top_tools cover the full retained history. Error rates include terminal transport and tool-result errors.

SQLite filters are applied before ordering and limiting, including for older records. The first v1.2.1 startup adds a timestamp-order index; on a large database this can take additional time and disk space. Existing audit rows are unchanged.

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"}.

mcp_audit_entries_total and mcp_audit_tool_calls_total use status="ok" for successful entries and status="rpc_error" for JSON-RPC errors. Since v1.2.1, non-RPC terminal failures use their bounded audit outcome (timeout, upstream_error, client_disconnect, malformed_upstream_response, cancelled, internal_error, denied, or rate_limited); MCP results with isError: true use tool_error. JSON-RPC errors retain rpc_error even when a failure outcome is present. Legacy entries without an outcome retain success/RPC classification, with tool-result errors recognized. Metric names and label sets are unchanged. For an error ratio, select status!="ok" rather than only rpc_error. OTLP spans use error status and error.type for these failures while preserving existing JSON-RPC error types.

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

Policy Engine

mcp-audit enforces ordered allow/deny rules before an operation reaches the upstream MCP server. policy.scope: tools_only preserves the legacy behavior; all_operations evaluates every client-originated MCP method. Denied operations return JSON-RPC error -32030 and are still written to the audit log.

policy:
  enabled: true
  scope: all_operations
  default_action: allow
  rules:
    - id: RESOURCE-001
      action: deny
      issuer: https://login.example.com/tenant
      role: operator
      server_id: filesystem
      method: resources/read
      name: file:///restricted
      reason: "Restricted resource"

Rules are evaluated in order. Empty fields and * match any value. Principal selectors are subject, issuer, role, and scope; operation selectors are method and name. Existing client_id, server_id, and tool_name rules remain valid. default_action: deny can be paired with explicit allow rules for stricter deployments. Set a rule id when durable audit provenance is needed.

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 terminal entry includes a ULID, UUIDv7 audit-operation identifier, outcome, timestamp, direction, transport, JSON-RPC method and request ID, operation name, redacted params/result, JSON-RPC error when present, duration, client/server identifiers, and a minimal authenticated principal. Signed entries contain both the compatible legacy signature and additive Integrity v2 metadata.

Example JSONL entry:

{
  "id": "01HY8G6Y8S6W9K6ZD7VJ4Q8X4R",
  "timestamp": "2026-05-25T12:34:56Z",
  "audit_operation_id": "019d2f6e-47ad-75ad-b506-b7990d8c11ba",
  "outcome": "success",
  "direction": "server→client",
  "transport": "http",
  "method": "tools/call",
  "request_id": "42",
  "mcp_name": "read_file",
  "tool_name": "read_file",
  "params": {
    "name": "read_file",
    "arguments": {
      "path": "/tmp/example.txt",
      "token": "[REDACTED]"
    }
  },
  "result": {"content": "ok"},
  "duration_ms": 18,
  "client_id": "oidc-client",
  "server_id": "filesystem",
  "principal": {
    "subject": "alice",
    "client_id": "oidc-client",
    "issuer": "https://login.example.com/tenant"
  },
  "policy": {
    "decision": "allow",
    "rule_id": "TOOLS-001"
  },
  "signature": "0123abcd...",
  "integrity": {
    "version": 2,
    "algorithm": "hmac-sha256",
    "key_id": "default",
    "signature": "4567efab..."
  }
}

The legacy signature keeps its original five-field contract. Integrity v2 uses RFC 8785 JSON canonicalization to authenticate the complete critical record, including the outcome, response or error, direction, and principal. See Audit integrity formats for the exact protected field set and compatibility rules.

Roadmap

• SIEM-friendly exports

• OTLP compression and trace context propagation

Contributing

Keep changes small, run make check (vet, build, and race tests), and prefer standard library behavior over new dependencies. Run make help for all development tasks. 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.