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

Tool	What it does
guardian_invoke_tool	Propose a tool call. ALLOW executes and returns the receipt; ASK returns a requestId held for human approval; DENY refuses with a reason code.
guardian_claim	Claim an approved ASK by requestId, execute, return the receipt.
guardian_receipt	Fetch the machine-readable evidence receipts for a request.

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": "…"
      }
    }
  }
}

Decision	What happens
ALLOW	The call is forwarded to the upstream server, then the capability is redeemed and the receipt recorded.
ASK	Nothing is forwarded. The exact call is held under a requestId; after a human approves, guardian_claim forwards exactly that call, once.
DENY	Nothing is forwarded, ever. The same applies if Guardian is unreachable.

• 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.