What can you do with this server?

Note: mcp-audit is a transparent proxy, so these are the upstream MCP server's tools (a filesystem server) that it audits, not tools it implements. Summary: The upstream server provides sandboxed filesystem access — reading, writing, editing, searching, listing, and moving files/directories within allowed directories. * Read files: read_text_file (text with optional head/tail line limits), read_file (deprecated alias), read_media_file (images/audio as base64 + MIME type), read_multiple_files (batch reads). * Write/modify files: write_file (create or fully overwrite), edit_file (exact line-based replacements with dry-run diff preview). * Move/rename files and directories with move_file; fails if destination exists. * Create directories, including nested paths, via create_directory (idempotent). * List directory contents: list_directory, list_directory_with_sizes (sortable by name/size), and recursive directory_tree with exclude patterns. * Search recursively with glob patterns (search_files) and exclude patterns. * Inspect metadata (size, timestamps, permissions, type) with get_file_info. * Discover scope: list_allowed_directories shows which directories are accessible; all operations are confined to those directories.

Which integrations are available for this server?

Exposes operational metrics for the proxy on a Prometheus-scrapeable /metrics endpoint (default port 9091), allowing monitoring of proxied MCP traffic, policies, and rate limits alongside an observability stack. Can persist the signed audit trail to a SQLite database (as an alternative to JSONL), giving a queryable local store of recorded JSON-RPC requests, responses, and policy decisions.

mcp-audit

by P4ST4S

Overview Schema Source Related Servers Discussions Admin

Hybrid

mcp-audit

codecov mcp-audit MCP server License Status GitHub 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.

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

mcp-audit 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

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.

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

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.

Available Tools

14 tools

create_directoryCreate DirectoryA

Idempotent

Create a new directory or ensure a directory exists. Can create multiple nested directories in one operation. If the directory already exists, this operation will succeed silently. Perfect for setting up directory structures for projects or ensuring required paths exist. Only works within allowed directories.

Name	Required	Description	Default
`path`	Yes

Output Schema

Name	Required	Description
`content`	Yes

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds significant behavioral details beyond annotations: nested directory creation, silent success on existing directory, and workspace restrictions. Annotations only say idempotent and not read-only, so description enriches understanding.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise: 5 sentences, front-loaded with action, no redundant words. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (1 parameter, idempotent, non-destructive), the description covers all necessary aspects: purpose, behavior, usage example, and constraints. Output schema exists, so return value details are not needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning to the 'path' parameter by implying support for nested paths and scoping to allowed directories. With 0% schema coverage, this is helpful, though more specifics on path format would be ideal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates new directories or ensures they exist, using specific verbs and resource. It distinguishes from sibling tools focused on files by explicitly mentioning directory creation and structure setup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context for use ('setting up directory structures', 'ensuring required paths exist') and includes a constraint ('only works within allowed directories'). However, it does not explicitly name alternatives or state when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

directory_treeDirectory TreeA

Read-only

Get a recursive tree view of files and directories as a JSON structure. Each entry includes 'name', 'type' (file/directory), and 'children' for directories. Files have no children array, while directories always have a children array (which may be empty). The output is formatted with 2-space indentation for readability. Only works within allowed directories.

Name	Required	Description	Default
`path`	Yes
`excludePatterns`	No

Output Schema

Name	Required	Description
`content`	Yes

TDQS

A4.1/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds substantial behavioral details beyond the 'readOnlyHint' annotation, including the recursive nature, entry structure (name, type, children), formatting (2-space indentation), and the constraint of working only within allowed directories. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four sentences, front-loaded with the main purpose, and every sentence adds value. No unnecessary words or repetition, making it concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema covering return values, the description is mostly complete, explaining output structure and formatting. However, it misses details about the 'excludePatterns' parameter, which is a minor gap. No discussion of depth limits or performance, but overall adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage for parameters. The tool description does not explain the 'excludePatterns' parameter, leaving its purpose and usage unclear. While 'path' is inferred, the lack of compensation for low schema coverage results in poor parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool gets a recursive tree view of files and directories as a JSON structure, specifying the verb, resource, and output format. It distinguishes itself from siblings like 'list_directory' (flat list) and 'search_files' (search), providing a specific and helpful purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus alternatives like 'list_directory' for flat listing or 'search_files' for search. It mentions 'Only works within allowed directories' but provides no explicit when-not or alternative guidance, leaving usage context clear but incomplete.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

edit_fileEdit FileA

Destructive

Make line-based edits to a text file. Each edit replaces exact line sequences with new content. Returns a git-style diff showing the changes made. Only works within allowed directories.

Name	Required	Description
`path`	Yes
`edits`	Yes
`dryRun`	No	Preview changes using git-style diff format

Output Schema

Name	Required	Description
`content`	Yes

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already set destructiveHint=true, so the editing nature is known. Description adds that edits replace exact line sequences (preserving unmatched lines), returns a git-style diff, and works only in allowed directories. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each serving a distinct purpose: what it does (line-based edits), how output is returned (diff), and constraints (allowed directories). No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given annotations (destructiveHint=true) and output schema (present), the description provides enough context for an agent to understand functionality, output, and constraints. Could mention return type or more about the edit array structure, but adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is low (33%), with only dryRun having a description. Description explains that 'oldText' must match exactly (implying substring replacement) and that dryRun previews changes as a git-style diff, but does not detail parameter formats or constraints beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses specific verb 'edit', resource 'text file', and mechanism 'line-based replacements of exact line sequences with new content'. Distinguishes from siblings like write_file (whole file overwrite) by emphasizing line-based edits and returning a git-style diff.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States 'Only works within allowed directories' but does not explicitly guide when to use edit_file versus alternatives like write_file or read_file. No exclusion criteria or context for when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_file_infoGet File InfoA

Read-only

Retrieve detailed metadata about a file or directory. Returns comprehensive information including size, creation time, last modified time, permissions, and type. This tool is perfect for understanding file characteristics without reading the actual content. Only works within allowed directories.

Name	Required	Description	Default
`path`	Yes

Output Schema

Name	Required	Description
`content`	Yes

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, indicating no destructive side effects. The description adds context about what metadata is returned (size, times, permissions, type) and the allowed directories constraint, going beyond the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with purpose, no extraneous information. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Description explains return fields and restrictions. With an output schema present (indicated), the description does not need to detail return structure. However, it could hint at required nature of path.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description does not add meaning to the sole 'path' parameter. With a simple string parameter, more guidance on format or constraints would be helpful.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Retrieve' and the resource 'detailed metadata about a file or directory', distinguishing it from sibling tools like read_file which read content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: 'perfect for understanding file characteristics without reading actual content' and notes restrictions ('Only works within allowed directories'). It does not explicitly mention when not to use or specific alternatives, but the context is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_allowed_directoriesList Allowed DirectoriesA

Read-only

Returns the list of directories that this server is allowed to access. Subdirectories within these allowed directories are also accessible. Use this to understand which directories and their nested paths are available before trying to access files.

Name	Required	Description	Default
No parameters

Output Schema

Name	Required	Description
`content`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description aligns with the readOnlyHint annotation and adds context about subdirectory accessibility. It does not contradict annotations and provides useful behavioral context beyond the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no wasted words. The first sentence immediately states the primary purpose, making it easy for an agent to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with zero parameters and an output schema, the description fully covers what the tool does, what it returns, and when to use it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, and schema coverage is 100%. The description does not need to add parameter details; baseline 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it returns the list of directories the server is allowed to access, with subdirectories. This verb+resource combination distinguishes it from siblings like 'list_directory' which lists contents of a specific directory.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises using this tool before trying to access files to understand available directories. It implies a prerequisite role, though it does not mention when not to use it or alternative tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_directoryList DirectoryA

Read-only

Get a detailed listing of all files and directories in a specified path. Results clearly distinguish between files and directories with [FILE] and [DIR] prefixes. This tool is essential for understanding directory structure and finding specific files within a directory. Only works within allowed directories.

Name	Required	Description	Default
`path`	Yes

Output Schema

Name	Required	Description
`content`	Yes

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide readOnlyHint=true, and the description adds concrete behavioral traits: results are prefixed with [FILE] and [DIR], and it only works within allowed directories. This goes beyond the annotation to inform the agent about output format and scope. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each adding value: the first states the core function, the second explains output format, the third gives use case and constraint. Efficient and front-loaded, though it could be slightly tighter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given low complexity (1 param, output schema exists, annotations present), the description covers the key aspects: purpose, output format, constraint, and use case. It is complete enough for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It mentions 'specified path' but provides no additional detail on format, relative vs absolute, or constraints beyond 'allowed directories'. This is adequate but minimal—the agent would benefit from more specific parameter guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Get a detailed listing of all files and directories' with a specific verb and resource. It distinguishes from siblings by mentioning the [FILE] and [DIR] prefixes and calls itself 'essential for understanding directory structure', setting it apart from tools like directory_tree or search_files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context by stating 'essential for understanding directory structure and finding specific files within a directory'. Also mentions constraint 'Only works within allowed directories'. However, it does not explicitly exclude alternatives or provide when-not guidance, missing a chance to differentiate from siblings like directory_tree or list_allowed_directories.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_directory_with_sizesList Directory with SizesA

Read-only

Get a detailed listing of all files and directories in a specified path, including sizes. Results clearly distinguish between files and directories with [FILE] and [DIR] prefixes. This tool is useful for understanding directory structure and finding specific files within a directory. Only works within allowed directories.

Name	Required	Description	Default
`path`	Yes
`sortBy`	No	Sort entries by name or size	name

Output Schema

Name	Required	Description
`content`	Yes

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true. The description adds behavioral details: results prefix [FILE] and [DIR], and the constraint 'Only works within allowed directories.' No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each adding distinct value: purpose, distinguishing feature, and usage scope. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, an output schema exists to document return values. The description covers purpose, constraint, and distinct formatting. Could mention error handling for invalid paths, but adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50% (path has no description). The description mentions 'specified path' but doesn't explain the sortBy parameter at all. It adds minimal value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it provides a detailed listing of files and directories with sizes, and distinguishes results with [FILE] and [DIR] prefixes. This differentiates it from sibling tools like list_directory (no sizes) and get_file_info (single file).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says it is 'useful for understanding directory structure and finding specific files,' which implies usage but does not explicitly state when to use this tool over alternatives or when not to use it. Missing exclusionary guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

move_fileMove FileA

Move or rename files and directories. Can move files between directories and rename them in a single operation. If the destination exists, the operation will fail. Works across different directories and can be used for simple renaming within the same directory. Both source and destination must be within allowed directories.

Name	Required	Description	Default
`source`	Yes
`destination`	Yes

Output Schema

Name	Required	Description
`content`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds behavioral detail beyond annotations (readOnlyHint=false, etc.), such as failure on existing destination and cross-directory capability. It does not contradict annotations and provides useful operational constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, front-loaded with the primary action, no redundant wording. Every sentence adds value about operation, constraints, or scope.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the moderately complex operation (move/rename with failure conditions), the description covers purpose, constraints, and scope. Output schema is present, so lack of return value detail is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by explaining that source and destination are file paths within allowed directories, adding meaning about their roles and constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it moves or renames files/directories, specifies it can do both in one operation, and distinguishes from sibling tools like copy or write by noting failure if destination exists.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use (move/rename) and conditions (destination must not exist, both paths in allowed directories). It lacks explicit comparison to alternatives but provides sufficient context for typical use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_fileRead File (Deprecated)A

Read-only

Read the complete contents of a file as text. DEPRECATED: Use read_text_file instead.

Name	Required	Description
`path`	Yes
`tail`	No	If provided, returns only the last N lines of the file
`head`	No	If provided, returns only the first N lines of the file

Output Schema

Name	Required	Description
`content`	Yes

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true. The description adds deprecation context but does not mention the head/tail parameters that modify behavior (partial reads). This gap leaves behavior partially undisclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise: two sentences front-load purpose and deprecation. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has three parameters and an output schema, the description is adequate for basic understanding but lacks detail on how head/tail affect output. The deprecation is the main extra value.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67% (path lacks description). The description adds no parameter-specific meaning; path remains undocumented, and head/tail descriptions from schema are not reinforced or elaborated.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool reads file contents as text and explicitly notes deprecation with a sibling alternative. The verb 'read' and resource 'file as text' are specific, and the deprecation distinguishes it from read_text_file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states 'DEPRECATED: Use read_text_file instead', providing clear guidance on when not to use this tool and directing to the preferred alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_media_fileRead Media FileC

Read-only

Read an image or audio file. Returns the base64 encoded data and MIME type. Only works within allowed directories.

Name	Required	Description	Default
`path`	Yes

Output Schema

Name	Required	Description
`content`	Yes

TDQS

C2.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true, so the description's addition of returning base64 data and MIME type and directory restriction adds context beyond annotations without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words, front-loaded with the core purpose. Efficiently conveys essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool is simple with one parameter and an output schema. Description covers allowed directories and return format but lacks details on error behavior, supported MIME types, or file size limits.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain the 'path' parameter's format, constraints, or expected input, leaving the agent without semantic guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states verb 'read' and resource 'image or audio file', and specifies return of base64 data and MIME type. However, it does not explicitly distinguish from sibling read_file, which may cause confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Only mentions an access constraint ('only works within allowed directories') but provides no guidance on when to use this tool versus similar siblings like read_file or read_text_file.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_multiple_filesRead Multiple FilesA

Read-only

Read the contents of multiple files simultaneously. This is more efficient than reading files one by one when you need to analyze or compare multiple files. Each file's content is returned with its path as a reference. Failed reads for individual files won't stop the entire operation. Only works within allowed directories.

Name	Required	Description	Default
`paths`	Yes	Array of file paths to read. Each path must be a string pointing to a valid file within allowed directories.

Output Schema

Name	Required	Description
`content`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, it reveals that individual file failures won't abort the operation, and the directory restriction. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no redundancy. First sentence states core purpose, second adds efficiency and behavioral details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given low complexity, annotations, and output schema presence, the description provides necessary behavioral and return context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%. Description adds that return includes file path as reference and partial failure behavior, adding value beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads multiple files simultaneously, which distinguishes it from sibling 'read_file' that reads single files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It highlights efficiency for analyzing or comparing multiple files, implying when to use this over single-file reads. It mentions allowed directories constraint but lacks explicit exclusions or alternative naming.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_text_fileRead Text FileA

Read-only

Read the complete contents of a file from the file system as text. Handles various text encodings and provides detailed error messages if the file cannot be read. Use this tool when you need to examine the contents of a single file. Use the 'head' parameter to read only the first N lines of a file, or the 'tail' parameter to read only the last N lines of a file. Operates on the file as text regardless of extension. Only works within allowed directories.

Name	Required	Description
`path`	Yes
`tail`	No	If provided, returns only the last N lines of the file
`head`	No	If provided, returns only the first N lines of the file

Output Schema

Name	Required	Description
`content`	Yes

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, and the description adds that it provides detailed error messages, handles various encodings, operates on text regardless of extension, and only works within allowed directories, exceeding what annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, front-loaded with the main purpose, and each sentence adds value: first on core function, second on error handling, third on usage. No redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool with output schema, the description covers reading behavior, encodings, error messages, directory restrictions, and partial reading options. It's fully adequate for an agent to correctly invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67% (head/tail described; path missing). The description adds usage guidance for head/tail but doesn't significantly enhance parameter meaning beyond the schema. Path parameter lacks detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads a file's complete contents as text, distinguishing it from siblings like 'read_media_file' (media) and 'read_multiple_files' (multiple files). It specifies handling encodings and error messages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says to use when examining a single file and explains partial reading via head/tail parameters. It lacks a 'when not to use' section but provides clear context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_filesSearch FilesA

Read-only

Recursively search for files and directories matching a pattern. The patterns should be glob-style patterns that match paths relative to the working directory. Use pattern like '.ext' to match files in current directory, and '**/.ext' to match files in all subdirectories. Returns full paths to all matching items. Great for finding files when you don't know their exact location. Only searches within allowed directories.

Name	Required	Description	Default
`path`	Yes
`pattern`	Yes
`excludePatterns`	No

Output Schema

Name	Required	Description
`content`	Yes

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, confirming no mutation. The description adds useful behavioral details: recursive search, returns full paths, and works with glob patterns relative to the working directory.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, front-loaded with main purpose, and includes examples without excessive verbosity. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists and annotations cover read-only behavior, the description adequately explains search behavior, pattern syntax, process, and scope ('allowed directories'). Slight gap on excludePatterns, but overall complete for a search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. It explains pattern syntax and scope but does not explicitly describe the 'path' parameter (only implies working directory context) and does not mention 'excludePatterns'. Partial but not fully comprehensive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Recursively search for files and directories matching a pattern' with specific verb and resource. It includes examples of glob patterns, and the purpose is distinct from sibling tools like list_directory or read_file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides context for when to use ('Great for finding files when you don't know their exact location') and mentions scope ('Only searches within allowed directories'), but does not explicitly state when not to use or mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

write_fileWrite FileA

DestructiveIdempotent

Create a new file or completely overwrite an existing file with new content. Use with caution as it will overwrite existing files without warning. Handles text content with proper encoding. Only works within allowed directories.

Name	Required	Description	Default
`path`	Yes
`content`	Yes

Output Schema

Name	Required	Description
`content`	Yes

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (destructiveHint=true, readOnlyHint=false, idempotentHint=true), description adds that it overwrites without warning and handles text encoding, providing useful behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, each adding essential information: purpose, caution, and encoding/directory constraint. No redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Lacks details on error handling (e.g., missing directory, invalid path) and prerequisites. With no parameter descriptions, agent may struggle to construct correct invocations despite output schema existing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage for parameters. Description does not clarify expected format for 'path' or 'content' (e.g., relative vs absolute, size limits, encoding specifics), leaving the agent to infer from names alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Create a new file or completely overwrite an existing file' – a specific verb and resource. Distinguishes from siblings like edit_file (which modifies partially) and read_file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Includes a caution about overwriting and a directory restriction, but does not explicitly contrast with siblings like edit_file for partial modifications. Lacks guidance on when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

14 tool updatesv0.1.0May 25, 2026
- First observedcreate_directory
- First observeddirectory_tree
- First observededit_file
- First observedget_file_info
- First observedlist_allowed_directories
- First observedlist_directory
- First observedlist_directory_with_sizes
- First observedmove_file
- First observedread_file
- First observedread_media_file
- First observedread_multiple_files
- First observedread_text_file
- First observedsearch_files
- First observedwrite_file

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored 2026-09-09 18:46 across 14 tools

Disambiguation2/5

read_file is a deprecated duplicate of read_text_file, and list_directory/list_directory_with_sizes/directory_tree all provide overlapping directory listings. Most other tools are distinct, but these boundary cases create real selection ambiguity for agents.

Naming Consistency4/5

Tool names overwhelmingly follow a snake_case verb_noun pattern like read_, write_, edit_, list_, move_, search_, and get_. Minor deviations are directory_tree lacking a verb and the deprecated read_file alongside read_text_file, but overall the naming is predictable.

Tool Count4/5

14 tools is within a reasonable scope for a filesystem server, but the set is slightly padded by the deprecated read_file and the near-duplicate list_directory_with_sizes. Removing or merging those would make the count feel tighter without losing functionality.

Completeness2/5

The server covers reading, writing, editing, moving, searching, and listing, but has no delete_file, delete_directory, or copy operation. Since write and edit are present, the lack of delete and copy leaves significant file-management dead ends for agents.

Maintenance

ActivityMaintained

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

agent-audit-logger-mcp
io.github.CSOAI-ORG
Hash-chained HMAC-signed audit log MCP for A2A (agent-to-agent) calls. Every tool-call, agent-ha...
Security Observability
2
https://api.meok.ai/v1/a2a/audit-logger
Occludra — MCP Gateway (AI Security Gateway)
ai.occludra
Security & DLP proxy for MCP: tool-poisoning scans, PII redaction on tool args/results. Beta.
Security Agent Orchestration
1
https://api.aisecuritygateway.ai/mcp
TokenZeroA
io.github.tokenzero-ai
LLM cost optimization gateway, repo token-waste auditor & model arbitrage MCP server.
AI & Machine Learning Developer Tools Code Analysis
61
https://tokenzero.sh/mcp
JiZhiMCPB
com.xn--5kvtwv52d
Host any HTTP API as MCP tools with a tamper-evident cross-agent settlement ledger.
AI & Machine Learning Weather Services Finance
211
https://mcp.xn--5kvtwv52d.com/mcp

Related MCP Servers

Filesystem MCP Serverofficial
File Systems Developer Tools
modelcontextprotocol
F
license
A
quality
A
maintenance
Node.js server implementing Model Context Protocol (MCP) for filesystem operations.
Updated 2 days ago (2026-11-05 06:26 UTC)
70
14
1,299,946 npm
91,812
-
GitHub MCP Server Plus
Version Control Developer Tools
PhialsBasement
A
license
B
quality
D
maintenance
MCP Server for the GitHub API, providing features for file operations, repository management, and advanced search, with automatic branch creation and comprehensive error handling.
Updated 2 years ago (2025-05-05 10:31 UTC)
18
6 npm
8
MIT
Postgres MCP
Databases Developer Tools Code Execution
crystaldba
A
license
A
quality
D
maintenance
Postgres Pro is an open source Model Context Protocol (MCP) server built to support you and your AI agents throughout the entire development process—from initial coding, through testing and deployment, and to production tuning and maintenance.
Updated 3 months ago (2026-08-17 05:06 UTC)
9
3,460
MIT
Brave Search MCP Serverofficial
Research & Data Search Text Summarization
brave
A
license
A
quality
B
maintenance
An MCP implementation that integrates the Brave Search API, providing comprehensive search capabilities including web, local business, image, video, news searches, and AI-powered summarization.
Updated 3 days ago (2026-11-04 02:04 UTC)
8
62,241 npm
1,561
MIT

mcp-audit

Why mcp-audit?

What This Is / Is Not

Supported Transports

Use Cases

Demo

Install

Quick Start

Examples

Configuration

HTTP authentication

Incoming TLS

Verify audit evidence

Claude Desktop

Dashboard

Prometheus Metrics

Policy Engine

OpenTelemetry

Audit Entries

Roadmap

Contributing

Community

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Filesystem MCP Serverofficial

Brave Search MCP Serverofficial