shieldclaw-mcp 0.1.0

A permission layer for AI agent tool calls — wrap any MCP server and enforce allow/deny/ask policy with full audit.

ShieldClaw-MCP

A permission layer for AI agent tool calls. Wrap any MCP server so every tools/call is checked against a policy — allowed, denied, or held for approval — and audited. We don't ask models to behave. We technically restrict what they can do.

  agent (Claude / GPT / any MCP client)
        │  tools/call: shell_exec "rm -rf /"
        ▼
  ┌───────────────┐
  │ ShieldClaw-MCP│  ──►  🚫 blocked by policy (never reaches the server)
  └───────────────┘
        │  tools/call: read_file
        ▼
  your real MCP server

Install

pip install shieldclaw-mcp

Use

Write a policy (policy.json):

{
  "default": "deny",
  "rules": {
    "read_file": "allow",
    "web_search": "allow",
    "db_delete": "deny",
    "shell_exec": "deny",
    "send_email": "ask",
    "*_secret": "ask"
  }
}

Wrap your MCP server. Wherever your agent/client launches the server, put shieldclaw-mcp wrap in front of it:

shieldclaw-mcp wrap --policy policy.json -- python my_mcp_server.py

For example, in a Claude Desktop mcpServers config, change the command from python my_mcp_server.py to shieldclaw-mcp wrap --policy /path/policy.json -- python my_mcp_server.py.

Decisions

Decision	Effect
allow	Forwarded to the server unchanged
deny	Blocked; the agent gets a JSON-RPC error, the server never sees it
ask	Blocked too (fail-closed) and tagged "requires approval"

Rules match exact tool names first, then glob patterns (db_*, *_secret), then fall back to default. The default default is deny.

Audit

Every decision is appended to ~/.shieldclaw-mcp/audit.jsonl. Tool arguments are never logged in full — only a short sha256 fingerprint, so you can correlate without leaking secrets. Set SHIELDCLAW_CONTROL_PLANE (or --control-plane URL) to also stream events to a dashboard.

Other commands

shieldclaw-mcp check --policy policy.json shell_exec   # -> deny
shieldclaw-mcp version

How it works

ShieldClaw-MCP is a transparent stdio proxy. The client launches it instead of the real server; it spawns the real server as a child and relays the newline-delimited JSON-RPC traffic both ways, intercepting only tools/call. Everything else (initialize, tools/list, notifications) passes through untouched, so it works with any compliant MCP server.

Develop

pip install -e ".[dev]"
pytest -q

License

MIT