DEV Community

Clarence Etnel
Clarence Etnel

Posted on • Originally published at github.com

"Put a security gateway in front of any MCP server in 5 minutes"

#mcp #python #ai #security

Put a security gateway in front of any MCP server in 5 minutes

If you're shipping an AI agent, you've probably wired it up to one or more MCP servers — for filesystem, GitHub, web search, payments. But here's the uncomfortable truth: most MCP setups today have zero auth, no rate limit, no audit log, and no spending control.

Anyone who can hit your MCP URL can drain your wallet, exfiltrate your files, or run up a bill on a paid API. There's no firewall. There's no if amount > $5, ask me first. There's nothing.

I just shipped mcp-guard, a tiny open-source gateway that sits between your agent and any MCP server. It's one pip install and one config file away from being useful.

pip install bonanza-mcp-guard
mcp-guard scan     # check your existing config for holes
mcp-guard serve    # wrap any MCP server in 30 seconds
Enter fullscreen mode Exit fullscreen mode

Here's what it does, why I built it, and how to wire it into your stack today.

The problem I kept running into

When I started shipping agents that talk to paid APIs (Stripe, OpenAI, Anthropic, Twilio, weather APIs), I wanted five things that MCP didn't give me out of the box:

  1. Authentication — who's calling this? Is the agent who it claims to be?
  2. Rate limits — per agent, per tool, per minute. Stop one misbehaving agent from blowing up the budget.
  3. Spend caps — wallet_pay to the value of $50 should require my approval. Always.
  4. Audit log — JSONL of every tool call: who, what, when, how much, what happened next.
  5. Approval queue — when something expensive or sensitive comes through, hold it. Send me a Slack message. Let me approve or deny from my phone.

MCP itself is great. It's a clean protocol. It doesn't try to be a security layer — and that's the right call for a protocol spec. But somebody has to build the security layer.

So I did.

What mcp-guard does

mcp-guard is a transparent proxy. You put it in front of any MCP server (stdio or HTTP) and it enforces:

  • 🔐 4 auth modes — none, API key (timing-safe SHA-256), JWT, or full OAuth2 with PKCE + Device flow
  • 🚦 Rate limits — 30 req/min, configurable per-agent or globally
  • 💸 Spend caps — require_approval_above: 5.0 → tool calls ≥ $5 get held in the approval queue
  • 🧾 Audit logs — JSONL, one line per call, ready for Splunk/Datadog/whatever
  • ✋ Approval queue — SQLite-backed. Agent gets -32004 approval_pending with an approval_id. Human runs mcp-guard approvals approve <id>. Done.
  • 🚫 Tool allowlist/denylist — deny: ["filesystem.delete", "wallet_pay"] per server
  • 📊 Prometheus metrics — GET /metrics on the HTTP gateway, drop-in for Grafana
  • 🐳 Docker image — docker run mcp-guard serve --config /etc/mcp-guard.yaml
  • 🔀 Multi-server routing — one gateway, many backends. Route wallet_pay → bonanza, read_file → filesystem, default → search.

The whole thing is zero required dependencies (pyyaml only if you want YAML configs) and ~2,900 lines of Python. You can read the whole codebase in an afternoon.

5-minute setup

1. Install 

pip install "bonanza-mcp-guard[yaml]"
Enter fullscreen mode Exit fullscreen mode

2. Scan your existing config 

mcp-guard scan
Enter fullscreen mode Exit fullscreen mode

This walks your Claude Desktop config (~/Library/Application Support/Claude/), Cursor config (~/.cursor/mcp.json), and any local mcp.json files. It flags:

  • 🔴 MCP servers without any auth
  • 🔴 Direct stdio commands (no wrapper, no policy, no logs)
  • 🟡 Remote URLs without obvious auth

It doesn't fix anything — just shows you the holes.

3. Wrap your MCP server

Create a config file:

# mcp-guard.yaml
auth:
  mode: api_key
  keys:
    - ${AGENT_API_KEY}

rate_limit:
  requests_per_minute: 30

policies:
  spend_cap_usd: 100.0
  require_approval_above: 5.0
  deny:
    - filesystem.delete_file
    - wallet_pay.bulk_transfer
  audit_log: ./audit.jsonl

servers:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
Enter fullscreen mode Exit fullscreen mode

Run it:

export AGENT_API_KEY=$(openssl rand -hex 32)
mcp-guard serve --config mcp-guard.yaml
Enter fullscreen mode Exit fullscreen mode

Your agent now hits mcp-guard instead of the bare MCP server. Everything works the same — but every call is now authenticated, rate-limited, audited, and (if it's expensive) held for approval.

4. Handle approvals

When the agent calls wallet_pay with $amount: 10, it gets back:

{
  "jsonrpc": "2.0",
  "id": 42,
  "error": {
    "code": -32004,
    "message": "Tool call held for approval",
    "data": {
      "approval_id": "appr_7f3a9c",
      "tool": "wallet_pay",
      "amount_usd": 10.0,
      "expires_at": 1719336000
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

You see this in your audit log, your Slack, your phone. You run:

mcp-guard approvals list
mcp-guard approvals approve appr_7f3a9c
Enter fullscreen mode Exit fullscreen mode

The agent retries, the call goes through, the audit log records your decision.

State is persistent (SQLite), so approvals survive restarts. And require_approval_above is per-tool, per-amount — $4.99 goes through, $5.01 waits.

5. Wire it up to your CI

mcp-guard ships with a GitHub Action that scans your MCP configs on every PR:

# .github/workflows/mcp-scan.yml
name: mcp-scan
on: [pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: c6zks4gssn-droid/mcp-guard/.github/workflows/mcp-scan.yml@main
Enter fullscreen mode Exit fullscreen mode

I tested it on mcp-guard itself with a .mcp.json fixture — it posted a live comment on the PR with 6 warnings, then merged clean. See the test PR for the actual output.

What I learned building this

A few things that surprised me:

1. The approval queue is the killer feature. I expected auth and rate limiting to be the headlines. Nope — the moment I shipped the approval queue, every single person who tested it said "oh, this is what I needed." When an agent wants to spend money, you want a human in the loop. That turns out to be the entire pitch.

2. JSON-RPC error codes are your API surface. -32004 approval_pending is now a stable contract that tools and dashboards can build against. Pick your extension codes carefully — they're forever.

3. PKCE without a JWT library is easier than I thought. mcp-guard's OAuth2 provider does HMAC-SHA256 signed access tokens with PKCE S256. Zero JWT deps, ~150 lines of code, RFC-compliant.

4. Docker is the secret weapon for stdio MCP. The HTTP transport (mcp-guard serve-http) is great, but the killer app is wrapping a stdio server in Docker, exposing it as HTTP, and putting a real auth layer in front. Suddenly every MCP server in the world is reachable from a browser tab.

What it's not

I want to be upfront about what's missing:

  • No per-agent tool allowlist yet. Today you can deny tools globally per server. Per-agent allowlists are on the roadmap (issue tracker).
  • No dashboard. Audit log is JSONL — great for piping into Datadog, bad for humans.
  • OAuth2 state is in-memory. Multi-replica deployments need a database backend (Redis or SQLite).

If any of those block you, open an issue. I ship fast when someone files a real bug.

Try it

If you're shipping agents that talk to MCP servers, give it 5 minutes. Scan your config, wrap one server, send one expensive tool call through it. If it doesn't immediately make sense why you need this, I'm happy to refund your time.

About me: I run Bonanza Labs — we ship security and tooling for the agent economy. mcp-guard is one of a dozen open-source packages we maintain. Follow me on X (@myopenclaw) if you want to see what we're working on next.

Top comments (0)