mcp-audit

A package-lock and flight recorder for MCP tool descriptions.

An MCP server's tool descriptions go straight into your model's context, and a server can change them at any time. mcp-audit sits transparently in front of any MCP server and:

• pins every tool the first time it is seen, and raises an alarm on every session after a description or schema changes, until a person reviews the change with mcp-audit lock diff and approves it with mcp-audit lock approve;
• records every message — which tool was called, with which arguments, and what came back — to a local JSONL file;
• flags prompt injection in tool descriptions and in tool results;
• blocks only what you tell it to, with optional allow/deny rules.

Everything runs locally. No account, no cloud, no telemetry: nothing leaves your machine unless you configure a webhook. One Go binary, Apache 2.0.

$ mcp-audit run -- npx -y @modelcontextprotocol/server-filesystem /tmp
mcp-audit dev | mode: stdio, wrapping "npx -y @modelcontextprotocol/server-filesystem /tmp"
mcp-audit config: built-in defaults (no config file found)
mcp-audit policy: shadow (recording only, nothing is blocked)
mcp-audit detectors: rug-pull, tool-poisoning, result-injection
mcp-audit audit log: /home/you/.mcp-audit/logs/events.jsonl

That is the whole setup. No config file, nothing blocked, everything recorded.

The recording is scripts/demo.sh, which runs the whole story end to end against a stub server, in a temp directory that leaves your real state alone:

./scripts/demo.sh                     # watch it
TYPING_SPEED=0 PAUSE=0 ./scripts/demo.sh   # run it instantly, as a smoke test
vhs docs/demo.tape                    # re-record docs/demo.gif

Install

No install needed — run it through npm, in front of the server you already use:

npx mcp-audit-proxy run -- npx -y @modelcontextprotocol/server-filesystem /tmp

Or download a binary for your platform from the latest release.

Note: the npm package and the release binaries are still 0.1.0, which predates mcp-audit lock and result scanning. Until 0.2.0 is out, build from source to get them.

Build from source — Go 1.24 or newer, no other dependencies:

go build -o mcp-audit ./cmd/mcp-audit

Or install straight into your GOBIN:

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

Quick start

Local (stdio) MCP servers

Put mcp-audit run -- in front of the command you already run:

mcp-audit run -- npx -y @modelcontextprotocol/server-filesystem /tmp

Remote (Streamable HTTP) MCP servers

Point the proxy at the upstream server and your client at the proxy:

mcp-audit serve --target https://example.com/mcp --listen :9000

Authentication is not touched: Authorization headers, OAuth flows and Mcp-Session-Id all pass through exactly as they arrive.

Read the log

Every message is one JSON line:

$ tail -1 ~/.mcp-audit/logs/events.jsonl | jq
{
  "timestamp": "2026-08-12T13:05:08.466Z",
  "event_id": "236d1568-e1f0-4ab4-ba75-f10f74f7b2c9",
  "client_id": "",
  "server_name": "server-filesystem",
  "direction": "request",
  "method": "tools/call",
  "tool_name": "read_file",
  

... [View full README on GitHub](https://github.com/firatmio/mcp-audit-proxy#readme)