guardian-mcp

@odingard/guardian-sdk

Guardian agent SDK — let an AI agent request governed capabilities and execute consequential actions under human authority. The agent proposes; the human decides. Every decision is deterministic (ALLOW / ASK / DENY) and every execution produces a tamper-evident receipt.

Hosted Guardian: https://guardian.odingard.com — free tier for developers (1 agent, 1 connection, 50 protected actions/month), no card required.

Install

npm install @odingard/guardian-sdk

Requires Node.js >= 20.

Quickstart

import { createGuardianClient } from "@odingard/guardian-sdk";

const guardian = createGuardianClient({
  baseUrl: "https://api.guardian.odingard.com",
  credential: process.env.GUARDIAN_AGENT_CREDENTIAL!, // gac1.… issued per agent
});

// 1. The agent asks for a capability — it never holds real credentials.
const result = await guardian.request({
  action: "tool.invoke",
  connectionId: "con_…",
  toolName: "refund_order",
  arguments: { orderId: "ord_123" },
});

if (result.ok && result.decision === "ALLOW") {
  // 2. Guardian minted a single-use capability. Execute it.
  const execution = await guardian.execute({
    requestId: result.requestId,
    capabilityToken: result.capabilityToken!,
  });
  console.log(execution.ok ? execution.receipt : execution.reasonCode);
} else if (result.ok && result.decision === "ASK") {
  // A human approves in the Guardian console, then:
  const granted = await guardian.claim(result.requestId);
  // …then execute as above once the capability arrives.
}
// decision === "DENY" → refused before execution, with a reason code.

What the agent can and cannot do

• The agent only ever holds a scoped, revocable agent credential (gac1.…).
• Provider secrets (API keys, OAuth tokens) live in the Guardian vault and are leased to the adapter at execution time — the agent never sees them.
• ASK decisions wait for a human. DENY stops the action before execution.
• receipts(requestId) returns the machine-readable proof of what happened, who authorized it, and what authority version applied.

MCP server

No code needed for MCP-native agents — @odingard/guardian-mcp is a stdio MCP server exposing guardian_invoke_tool, guardian_claim and guardian_receipt. Listed on the official MCP registry as io.github.Odingard/guardian-mcp.

npm install -g @odingard/guardian-mcp

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

Plans and limits

Guardian is free for individual developers. Usage is metered per month on protected actions (the consequential things an agent can cause); reading receipts and requests is never metered.

Plan	Connections	Agents	Protected actions / month
Free	1	1	50
Personal	10	25	50,000
Growth	50	250	500,000
Business	250	1,000	5,000,000

Over a limit, the API returns 403 PLAN_LIMIT_EXCEEDED naming your plan, the limit, and current usage. Upgrade in the console → Billing (POST /v1/billing/checkout issues a Stripe Checkout URL).

License

Apache-2.0

Provenance

Canonical development happens in the Odingard Guardian monorepo; this repository is the standalone open-source distribution of the agent SDK (source mirrored, Apache-2.0). Issues and contributions welcome here.