👁️ mcp-warden

MCP observability and control plane.

pip install mcp-warden

mcp-warden audit -- your-mcp-server [args...]
mcp-warden guard --max-calls-per-minute 30 --block-tool write_query -- any-mcp-server
mcp-warden both  --max-calls-per-minute 60 --max-response-kb 512 -- any-mcp-server
mcp-warden log   --tail 20

The problem

MCP clients like Cline and Claude Desktop can call tools on any connected server with no visibility and no throttle.

An agent in a loop can:

• Call sql_query hundreds of times a minute, burning your API budget
• Pull back 50 MB of data in a single tool call
• Hit a tool you meant to leave off
• Fail repeatedly and nobody notices until the damage is done

mcp-warden fixes all of this — for any MCP server, without touching it.

How it works

MCP client (Cline / Claude Desktop)
    │  stdin/stdout
    ▼
mcp-warden  ◄──── audit + guard
    │  subprocess stdin/stdout
    ▼
Upstream MCP server (any MCP server)

mcp-warden is a transparent JSON-RPC relay. The client never knows it's there. The upstream server never knows it's there. Every tools/call passes through the audit and guard layer in the middle.

Latency impact: ~0.1–0.5 ms per message — negligible against typical LLM tool call round trips of 100 ms to 10 s.

Install

pip install mcp-warden

Zero runtime dependencies. Pure Python 3.9+ stdlib.

Usage

Audit — log everything

mcp-warden audit \
  --audit-log ~/.mcp_warden/audit.jsonl \
  --session-id cline \
  -- your-mcp-server [args...]

Each line of the JSONL log is a self-contained event:

{"ts":"2025-03-04T10:22:01.234Z","session_id":"cline","direction":"request","msg_id":"1","method":"tools/call","tool":"sql_query","args":{"sql":"SELECT TOP 10 * FROM Product"}}
{"ts":"2025-03-04T10:22:01.376Z","session_id":"cline","direction":"response","msg_id":"1","method":"tools/call","tool":"sql_query","duration_ms":142.3,"content_len":4821,"is_error":false,"error_msg":null}

Guard — rate limits + blocking

mcp-warden guard \
  --max-calls-per-minute 30 \
  --per-tool-limit sql_query:10 \
  --block-tool write_query \
  --max-response-kb 512 \
  --max-errors 5 \
  -- any-mcp-server

When a limit is hit, the agent gets a clear error:

Tool 'write_query' is in the blocked list.
Global rate limit reached (30 calls/min). Retry in ~42s.
Response too large (1024.0 KB > 512 KB limit). Consider narrowing your query.
Circuit breaker open — too many consecutive errors. Auto-reset in 58s.

Both — recommended

mcp-warden both \
  --audit-log ~/.mcp_warden/audit.jsonl \
  --max-calls-per-minute 60 \
  --per-tool-limit sql_query:20 \
  --block-tool write_query \
  --max-response-kb 1024 \
  --max-errors 3 \
  -- your-mcp-server [args...]

View the log

mcp-warden log --tail 20
mcp-warden log --tail 50 --filter-tool sql_query
mcp-warden log --errors-only
mcp-warden log --json | jq 'select(.is_error == true)'

Claude Desktop / Cline setup

Create a wrapper script:

#!/bin/bash
# ~/.config/mcp_warden/mydb.sh
exec mcp-warden both \
  --audit-log ~/.mcp_warden/mydb.jsonl \
  --max-calls-per-minute 60 \
  --max-response-kb 1024 \
  --max-errors 3 \
  -- /path/to/your-mcp-server.sh

Reference it in your MCP config:

{
  "mcpServers": {
    "mydb": { "command": "/Users/you/.config/mcp_warden/mydb.sh" }
  }
}

Guard options

Audit log schema

Python API

from mcp_warden import MCPWarden, AuditLogger
from mcp_warden.guard import GuardConfig

proxy = MCPWarden(
    cmd=["your-mcp-server", "--arg", "value"],
    audit_logger=AuditLogger(path="./audit.jsonl", session_id="my-agent"),
    guard_config=GuardConfig(
        max_calls_per_minute=30,
        per_tool_limits={"sql_query": 10},
        blocked_tools=["write_query"],
        max_response_kb=512,
        max_errors_before_circuit_break=3,
    ),
)
proxy.run()

Roadmap

• Async audit write queue (decouple disk I/O from relay path)
• HTTP/SSE transport support
• Prometheus metrics endpoint
• Per-session budget and cost tracking
• Webhook alerts on circuit break / blocked calls
• Web dashboard for log exploration

Contributing

git clone https://github.com/raj8github/mcp-warden
cd mcp-warden
pip install -e ".[dev]"
pytest tests/ -v

See CONTRIBUTING.md.

License

MIT — see LICENSE