Tool Pick | mcp-guardrail — Add an Approval and Audit Layer to Every MCP Tool Call

🌏 中文版

Tool Info

What Problem Does It Solve

Have you ever wired up a bunch of MCP servers — GitHub, databases, filesystem, shell — letting your agent call them directly, without ever stopping to ask: "Is there a tool in this list that I actually don't want the agent to invoke on its own?" Most teams authorize MCP servers as a unit: if the agent can connect, it can call every tool under that server, including destructive ones like github.delete_repo or shell.exec. On top of that, many people hard-code API keys directly in their mcpServers config files — once that config gets pasted into an issue or committed, the keys are leaked.

mcp-guardrail is a stdio JSON-RPC proxy that sits between the MCP client and the real MCP server. Instead of launching the real server directly, you route it through mcp-guardrail run with a policy.yaml (allow/deny rules with glob patterns, matched top-down, defaulting to deny). Every tools/call goes through a policy check first — blocked requests get an error response without ever reaching the real server. Regardless of the verdict, all calls are logged to a local JSONL audit file that you can tail, grep, or aggregate later. It also includes a narrowly scoped secret scanner that catches hard-coded API keys and tokens in config files (AWS, GitHub, Slack, OpenAI, Anthropic, PEM private keys, etc.) and can run as a CI check — non-zero exit on any finding.

Good fit: teams that already have multiple high-risk MCP servers wired up (GitHub, shell, database) and want an auditable boundary for "what can the agent actually do" rather than relying on the agent's self-restraint; or anyone who wants to run its scan command across their entire MCP config directory to catch hard-coded secrets.

Quick Start

Installation

git clone https://github.com/KiaanKothari/mcp-guardrail.git
cd mcp-guardrail
pip install -e .

Basic Usage

# 1. Generate a starter policy file
mcp-guardrail init

# 2. Replace the direct MCP server launch with one routed through guardrail
#    (in your Claude Code / Claude Desktop mcpServers config)

{
  "mcpServers": {
    "github": {
      "command": "mcp-guardrail",
      "args": [
        "run", "--policy", "/path/to/policy.yaml", "--",
        "npx", "-y", "@modelcontextprotocol/server-github"
      ]
    }
  }
}

# 3. See what just happened
mcp-guardrail report

Advanced Usage

# Scan a config directory for hard-coded API keys/tokens — plug into CI
mcp-guardrail scan ~/.config/claude/

Policy rules in policy.yaml are matched top-down; the first matching pattern wins, and unmatched calls fall back to default:

default: deny

rules:
  - tool: "github.create_issue"
    action: allow
  - tool: "github.delete_*"
    action: deny
    note: "destructive GitHub actions are never auto-approved"

Comparison with Alternatives

Caveats

• Limited transport support: currently only handles standard newline-delimited JSON-RPC 2.0 over stdio. MCP servers using Content-Length framing or other transports require modifying the read loop in proxy.py.
• Not yet on PyPI; early stage: install-only via clone + pip install -e .. Created on 2026-08-24 with a single contributor and 2 stars — the policy schema may still change.
• Policy only matches tool names: there is no parameter-level filtering yet (e.g., allowing the same tool only for certain input paths). The README itself lists this as a planned feature.

Takeaway

Most people think about "can this agent connect to this MCP server?" but rarely about the next layer down — "once connected, which specific tools can it call?" mcp-guardrail highlights a gap: the default trust boundary in the MCP ecosystem is the entire server, not the individual tool. That gap is exactly where it aims to fit.

References

• mcp-guardrail GitHub repo: project overview, README, install instructions, policy schema, proxy architecture, and license (MIT) — all sourced from the official README.
• Model Context Protocol official docs: MCP protocol introduction.