Agent Guardrail MCP server

Guardrail

<!-- mcp-name: io.github.rudimentall1/agent-guardrail -->

📄 Read the white paper

Put a policy firewall between an AI agent and every irreversible action.

Your agent wants to run a shell command, send an email, or move money. Guardrail checks that request against rules you wrote, before it happens, and either lets it through, asks a human, or blocks it — with a plain- English reason every time.

60-second quickstart

git clone <this repo> && cd agent-guardrail
pip install -r requirements.txt

python3 cli.py check --agent trading-agent-001 --tool wallet.transfer \
  --args '{"amount": 9999, "to": "0xabc"}'

Or pip install guardrail-mcp gives you a guardrail command directly — same output, no repo checkout required (falls back to the policy bundled in the package if you don't point --policy at your own file):

guardrail check --agent trading-agent-001 --tool wallet.transfer \
  --args '{"amount": 9999, "to": "0xabc"}'

{
  "decision": "BLOCK",
  "matched_rules": [
    {"rule": "numeric_cap_exceeded", "severity": "BLOCK",
     "message": "amount=9999.0 exceeds cap 5 for 'wallet.transfer' (unknown agent)"}
  ]
}

That's it — no server, no account, no API key. policies/default.yaml is the file that decided this; open it and change the numbers to match your own rules.

Why this, not another "AI risk scoring" tool

Most "AI agent security" projects (including an earlier project of mine) lean on statistical risk scores computed from data nobody can actually verify at build time — wallet age, "reputation," contract "risk" — which either requires paid data feeds you don't have yet, or quietly becomes mock data pretending to be real. Fine for prototyping, dishonest to ship.

Guardrail only makes claims it can back up. Every check is a deterministic rule — a blocklist entry, a regex match, a numeric cap, a rate limit — evaluated against a policy file you write and can audit yourself, backed by a real, persistent audit log (SQLite) you can query. Nothing here pretends to know something it doesn't.

It's also not blockchain-specific. Shell execution, email, HTTP requests, file deletion, database writes, crypto transactions — same engine, same policy file, same rules.

Four ways to use it

1. CLI — for testing a policy by hand

Shown above. No setup, instant feedback while you write rules.

2. MCP server (mcp_server.py) — the easy on-ramp, advisory

Exposes guardrailcheck, guardrailrecordoutcome, and guardrailagent_history as MCP tools any MCP-compatible agent (Claude Desktop, Claude Code, custom MCP clients) can call.

{
  "mcpServers": {
    "guardrail": {
      "command": "python3",
      "args": ["/absolute/path/to/agent-guardrail/mcp_server.py"],
      "env": { "GUARDRAIL_POLICY": "/absolute/path/to/agent-guardrail/policies/default.yaml" }
    }
  }
}

Then tell your agent (in its system prompt) to always call guardrail_check before spending money, deleting data, messaging someone externally, or running code.

Be clear-eyed about its limit: like any MCP tool, nothing stops the calling model from just not invoking it. This only helps if the agent is instructed to always check first — for a guarantee it can't skip, see #3.

3. guardrail.decorator.enforce — the real guarantee

Wraps the actual Python function that performs a tool's side effect. The check runs in your code, before that function executes — the model never gets a chance to call the real function directly.

from guardrail.decorator import enforce, BlockedActionError

@enforce(engine, tool_name="send_email")
def send_email(agent_id: str, to: str, subject: str, body: str):
    ...  # only runs if the decision is ALLOW, or WARN-and-confirmed

Shortened. The full README is on GitHub.