P4ST4S/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.
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.
Download the latest prebuilt binary and run:
Run with Docker:
Install from source with Go:
To pin a specific release for reproducible installs, see
INSTALL.md.
Quick Start
Run in stdio mode:
On Windows PowerShell, generate the secret and set it as an environment variable:
Run in HTTP mode:
Run with Docker Compose:
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, 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.upstream_timeout_ms | 30000 | HTTP upstream request timeout in milliseconds. |
| proxy.forward_headers | empty | Request headers allowed to bypass the default upstream strip list. Use ["Authorization"] only when the upstream MCP HTTP server requires bearer-token auth. |
| proxy.tls.ca_file | empty | Optional CA bundle used to verify an HTTPS upstream MCP server. |
| proxy.tls.server_name | empty | Optional TLS server name override for the upstream MCP server. |
| proxy.tls.insecure_skip_verify | false | Skip upstream TLS certificate verification. Intended only for local testing. |
| proxy.tls.client_cert_file | empty | Optional client certificate for upstream mTLS. Must be configured with proxy.tls.client_key_file. |
| proxy.tls.client_key_file | empty | Optional client key for upstream mTLS. Must be configured with proxy.tls.client_cert_file. |
| proxy.retry.max_retries | 0 | Maximum conservative retry attempts for safe HTTP upstream requests. Off by default. |
| proxy.retry.initial_interval_ms | 200 | Initial upstream retry backoff. |