# mcp-audit

![Go](https://img.shields.io/badge/Go-1.22%2B-00ADD8)
[![CI](https://github.com/P4ST4S/mcp-audit/actions/workflows/ci.yml/badge.svg)](https://github.com/P4ST4S/mcp-audit/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/P4ST4S/mcp-audit/graph/badge.svg)](https://codecov.io/gh/P4ST4S/mcp-audit)
[![mcp-audit MCP server](https://glama.ai/mcp/servers/P4ST4S/mcp-audit/badges/score.svg)](https://glama.ai/mcp/servers/P4ST4S/mcp-audit)
![License](https://img.shields.io/badge/License-Apache--2.0-blue)
![Status](https://img.shields.io/badge/Status-stable-brightgreen)
[![GitHub Discussions](https://img.shields.io/badge/discussions-join-blue?logo=github)](https://github.com/P4ST4S/mcp-audit/discussions)

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](ARCHITECTURE.md).

## Why mcp-audit?

[The MCP 2026 roadmap](https://modelcontextprotocol.io/development/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.

```text
+-------------+    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

![mcp-audit demo](demo/mcp-audit-demo.gif)

## Install

For detailed platform-specific instructions and troubleshooting, see
[INSTALL.md](INSTALL.md).

The current release is **v1.3.0**. See the [changelog](CHANGELOG.md#130---2026-10-17)
and [migration guide](docs/V1.3_MIGRATION.md) before upgrading.

Download the latest prebuilt binary and run:

```bash
# 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:

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

Install from source with Go:

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

To pin a specific release for reproducible installs, see
[INSTALL.md](INSTALL.md#choosing-a-version).

## Quick Start

Run in stdio mode:

```bash
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:

```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:

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

Run with Docker Compose:

```bash
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](examples/cursor/README.md)
- [Continue stdio configuration](examples/continue/README.md)
- [VS Code stdio configuration](examples/vscode/README.md)
- [Claude Desktop stdio configuration](examples/claude-desktop/README.md)
- [Zed stdio configuration](examples/zed/README.md)

## 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](docs/V1.2_MIGRATION.md) 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.

| Key | Default | Description |
| --- | --- | --- |
| `proxy.transport` | `stdio` | Proxy transport: `stdio` or `http`. |
| `proxy.upstream` | required | Stdio command or HTTP upstream URL. |
| `proxy.bind_address` | empty (legacy) | HTTP listen address. The distributed config uses `127.0.0.1`; an omitted value retains all-interface binding with a warning until v2.0.0. |
| `proxy.port` | `4422` | HTTP listen port. |
| `proxy.upstream_timeout_ms` | `30000` | HTTP upstream request timeout in milliseconds. |
| `proxy.http.max_request_body_bytes` | `10485760` | Maximum incoming HTTP request body size. Oversized requests return `413`. |
| `proxy.http.max_header_bytes` | `1048576` | Maximum incoming HTTP header size. |
| `proxy.http.read_header_timeout` | `10s` | Time allowed to read request headers. |
| `proxy.http.read_timeout` | `30s` | Time allowed to read the full request. |
| `proxy.http.write_timeout` | `30s` | Time allowed to write the response. |
| `proxy.http.idle_timeout` | `120s` | Keep-alive idle timeout. |
| `proxy.http.allowed_origins` | empty | Optional exact browser Origin allowlist. Requests without `Origin` remain valid non-browser clients. |
| `proxy.http.allowed_hosts` | empty | Optional Host allowlist for DNS-rebinding protection. Entries are hostnames or IP addresses with optional ports. |
| `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.enabled` | `false` | Serve incoming proxy connections over TLS. Requires `proxy.tls.cert_file` and `proxy.tls.key_file`. |
| `proxy.tls.cert_file` | empty | PEM certificate chain for incoming TLS connections. |
| `proxy.tls.key_file` | empty | PEM private key for incoming TLS connections. |
| `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. |
| `proxy.retry.max_interval_ms` | `2000` | Maximum upstream retry backoff. |
| `proxy.client_id` | `claude-desktop` | Client identifier written to audit entries. |
| `proxy.server_id` | `filesystem` | Server identifier written to audit entries. |
| `auth.mode` | `none` | HTTP client authentication mode: `none`, `static_bearer`, or `oidc`. None uses the explicitly configured static principal for local compatibility. |
| `auth.static.bearer_token` | empty | Pre-shared bearer token for `static_bearer` mode. Prefer `MCP_AUDIT_STATIC_BEARER_TOKEN`; minimum 32 bytes. |
| `auth.static.subject` | `local` | Trusted subject for the local or static-bearer principal. |
| `auth.static.client_id` | empty | Principal client identifier. Empty inherits `proxy.client_id`. |
| `auth.static.issuer` | `static` | Principal issuer label. |
| `auth.static.roles` | empty | Roles attached to the principal for later policy evaluation. |
| `auth.static.scopes` | empty | Scopes attached to the principal for later policy evaluation. |
| `auth.oidc.issuer` | empty | Required exact JWT issuer in `oidc` mode. |
| `auth.oidc.audience` | empty | Required JWT audience in `oidc` mode. |
| `auth.oidc.jwks_uri` | empty | Remote JWKS URL. HTTPS is required except on loopback. |
| `auth.oidc.client_id_claim` | `client_id` | Required claim projected to the principal client ID. |
| `auth.oidc.roles_claim` | `roles` | Optional string or string-array roles claim. |
| `auth.oidc.scopes_claim` | `scope` | Optional space-separated string or string-array scopes claim. |
| `auth.oidc.allowed_methods` | asymmetric methods | Explicit JWT signature algorithm allowlist. |
| `auth.oidc.clock_skew` | `30s` | Maximum clock skew for `exp` and `nbf` validation. |
| `auth.oidc.http_timeout` | `5s` | JWKS HTTP fetch and unknown-key refresh timeout. |
| `auth.oidc.refresh_interval` | `5m` | Background JWKS rotation refresh interval. |
| `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. Startup fails unless a non-blank secret is configured. |
| `audit.secret` | empty | HMAC secret. Prefer `MCP_AUDIT_SIGNING_SECRET`. |
| `audit.signing.key_id` | `default` | Key identifier stored with Integrity v2 metadata. |
| `audit.durable` | `false` | Wait for a storage durability barrier before acknowledging an audit, including with async batching. See [durability and checkpoint limits](docs/V1.3_MIGRATION.md). |
| `audit.async.enabled` | `false` | Enable asynchronous batched audit writes through a bounded ring buffer. |
| `audit.async.queue_size` | `4096` | Maximum queued audit entries before backpressure blocks writers. |
| `audit.async.batch_size` | `128` | Maximum entries written per storage batch. |
| `audit.async.flush_interval_ms` | `1000` | Maximum time before a partial batch is flushed. |
| `audit.rotation.max_size_bytes` | `0` | Maximum active JSONL file size before archive rotation. `0` disables built-in rotation. |
| `audit.rotation.max_files` | `0` | Maximum number of rotated JSONL archives to keep. `0` disables retention. |
| `audit.rotation.interval` | empty | Optional time-based JSONL rotation interval: `hourly` or `daily`. Empty disables time-based rotation. |
| `audit.rotation.max_age_days` | `0` | Delete JSONL archives whose filename rotation timestamp is older than this many days. `0` disables age retention. |
| `middleware.rate_limit.enabled` | `true` | Enable per-client, per-tool token buckets. |
| `middleware.rate_limit.requests_per_minute` | `60` | Allowed requests per minute per authenticated `(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. |
| `policy.enabled` | `false` | Enable synchronous allow/deny policy checks. |
| `policy.default_action` | `allow` | Fallback action when no policy rule matches: `allow` or `deny`. |
| `policy.scope` | `tools_only` (legacy) | Methods evaluated by policy: `tools_only` or `all_operations`. The distributed config opts into `all_operations`. |
| `policy.rules` | empty | Ordered first-match allow/deny rules. Optional `id` is retained as audit provenance. Existing `client_id`, `server_id`, and `tool_name` selectors remain valid; principal selectors are `subject`, `issuer`, `role`, and `scope`, with generic operation selectors `method` and `name`. |
| `dashboard.enabled` | `true` | Serve the dashboard. |
| `dashboard.bind_address` | `127.0.0.1` | Dashboard listen address. Set explicitly, for example to `0.0.0.0`, only when the dashboard is protected by network controls or auth. |
| `dashboard.port` | `9090` | Dashboard listen port. |
| `dashboard.auth.token` | empty | Optional bearer token required as `Authorization: Bearer <token>` for dashboard HTML and API requests. |
| `metrics.enabled` | `true` | Serve Prometheus metrics on a separate HTTP endpoint. |
| `metrics.port` | `9091` | Metrics listen port. |
| `metrics.path` | `/metrics` | Metrics HTTP path. |
| `metrics.include_go_metrics` | `true` | Include Go runtime metrics. |
| `metrics.include_process_metrics` | `true` | Include process metrics. |
| `metrics.tool_labels` | `true` | Include `tool_name` and `client_id` labels for tool-level metrics. Disable to minimize label cardinality. |
| `otel.enabled` | `false` | Export `tools/call` audit entries as OTLP/HTTP JSON spans. |
| `otel.endpoint` | `http://localhost:4318` | OTLP HTTP endpoint base URL. `/v1/traces` is appended automatically. |
| `otel.service_name` | `mcp-audit` | OpenTelemetry `service.name` resource attribute. |
| `otel.headers` | empty | Additional OTLP HTTP headers, for example `Authorization` or API key headers. |
| `otel.tls.ca_file` | empty | Optional CA bundle used to verify the OTLP endpoint. |
| `otel.tls.server_name` | empty | Optional TLS server name override. |
| `otel.tls.insecure_skip_verify` | `false` | Skip OTLP TLS certificate verification. Intended only for local testing. |
| `otel.retry.max_retries` | `3` | Maximum OTLP retry attempts after a failed export request. |
| `otel.retry.initial_interval_ms` | `200` | Initial OTLP retry backoff. |
| `otel.retry.max_interval_ms` | `2000` | Maximum OTLP retry backoff. |
| `otel.queue_size` | `1024` | Maximum queued audit entries before trace exports are dropped. |
| `otel.batch_size` | `64` | Maximum spans per OTLP export request. |
| `otel.flush_interval_ms` | `1000` | Maximum time before a partial OTLP batch is exported. |
| `otel.timeout_ms` | `5000` | OTLP HTTP request timeout. |

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:

```yaml
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:

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

```yaml
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:

```yaml
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:

```yaml
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.

```yaml
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:

```text
--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:

```bash
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:

```bash
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](docs/V1.3_MIGRATION.md) for storage, backup, and trust
requirements.

## Claude Desktop

Configure Claude Desktop to spawn `mcp-audit` instead of the upstream MCP server:

```json
{
  "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.

```yaml
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:

```text
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.

```yaml
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](examples/docker-compose-observability/README.md).

## 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.

```yaml
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.

```yaml
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:

```json
{
  "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](docs/AUDIT_INTEGRITY.md) 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](STABILITY.md).

See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, PR expectations, and project principles. See [CHANGELOG.md](CHANGELOG.md) for release history.

## Community

- [Discussions](https://github.com/P4ST4S/mcp-audit/discussions): questions, ideas, and design conversations
- [Issues](https://github.com/P4ST4S/mcp-audit/issues): bug reports and concrete feature requests
- Security: see [SECURITY.md](SECURITY.md) for the private vulnerability reporting process

## License

Apache-2.0. See [LICENSE](LICENSE).