Guardian MCP

@odingard/guardian-mcp

MCP server that routes an agent's tool calls through Guardian — Human Authority Infrastructure for Autonomous AI. Every tool call gets a deterministic ALLOW / ASK / DENY decision before anything executes; DENY means the action never runs, and ASK holds it until a human approves.

Install

npm i -g @odingard/guardian-mcp

Configure your MCP client

{

"mcpServers": { "guardian": { "command": "guardian-mcp", "env": { "GUARDIAN_BASE_URL": "https://guardian-api.odingard.com", "GUARDIAN_AGENT_CREDENTIAL": "gak_…", "GUARDIAN_CONNECTION_ID": "con_…" } } } }

GUARDIAN_ADAPTER_ID optionally overrides the tool adapter.

Tools

Nothing executes without a Guardian capability — the model's output is a proposal, never an action.

Govern an existing MCP server: guardian-mcp proxy (0.3)

Put Guardian in front of any stdio MCP server you already use, such as WhatsApp, Stripe, Shopify, a filesystem or a database. The client sees the upstream server's tools unchanged, and every call is decided first:

{

"mcpServers": { "whatsapp-governed": { "command": "guardian-mcp", "args": ["proxy", "--", "npx", "-y", "your-whatsapp-mcp-server"], "env": { "GUARDIAN_BASE_URL": "https://guardian-api.odingard.com", "GUARDIAN_AGENT_CREDENTIAL": "gac1.…", "GUARDIAN_CONNECTION_ID": "con_…", "WHATSAPP_TOKEN": "…" } } } }

• guardian_claim and guardian_receipt are added to the tool list.
• The upstream server never receives GUARDIAN_* settings, so it never sees the agent credential.
• Decision-gated: an allowed call runs upstream before the capability is redeemed. A refusal at redemption is reported as an incident (localEffectRan: true), never as success.
• First-run setup: in the Guardian console, connect a tool server and add each upstream tool as "My own code (record-only)". Then allow those tools for the agent.
• Since 0.3.1 the proxy does not try to register tools itself.
• GUARDIAN_AUTO_REGISTER=true turns that back on, but it is denied unless the agent's grant pins mcp.install.
• When Guardian refuses, the result says what to fix.
• Held calls live in the proxy process. Restarting the proxy drops them, and nothing is forwarded.

guardian-mcp --help prints usage. A missing setting prints a one-line message naming it instead of a stack trace.

See what you are about to govern: guardian-mcp tools

Before putting a server behind the proxy, list its tools along with a suggested Guardian mode for each. This needs no Guardian credential:

npx -y @odingard/guardian-mcp tools -- npx -y @modelcontextprotocol/server-filesystem ./data

Tool            Suggested     Why

read_file Allow server marks it read-only write_file Ask me first "write" may change something delete_branch Ask me first server marks it destructive createIssue Ask me first "create" may change something ⚠ name not accepted by Guardian

How the suggestions are made:

• The server's own MCP annotations (readOnlyHint, destructiveHint) are used first.
• Otherwise the tool's verb decides. get, list and search suggest Allow; everything else suggests Ask.

They are suggestions only: you set the real modes in the console. Tool names that break Guardian's naming rule are flagged, because every call to them would be denied. Add --json for machine-readable output.

License

Apache-2.0. Canonical development happens in the Odingard Guardian monorepo.