Skip to main content
Glama
Guardian by Odingard

Guardian by Odingard

@odingard/guardian-mcp

Guardian MCP server

Guardian is the trust layer for agent commerce. Human Authority Infrastructure for Autonomous AI: the agent proposes; the human decides.

This MCP server routes an agent's tool calls through Guardian. 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

Related MCP server: mcp-boundary

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

GUARDIAN_ADAPTER_ID optionally overrides the tool adapter.

Tools

Tool

What it does

Annotations

guardian_invoke_tool

Run a registered tool through Guardian. ALLOW runs it and returns the record; ASK runs nothing and returns a requestId to claim after the person approves; DENY runs nothing and gives a reason code.

destructive, not idempotent, open world

guardian_claim

Run a request held as ASK, after the person approves it, and return the record. Before approval it answers ASK again. An approval is used once: claiming again does not run the call twice.

destructive, not idempotent, open world

guardian_record

Fetch the evidence records Guardian holds for a requestId. Runs and changes nothing.

makes no changes, idempotent, closed world

Each tool has a title, MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) and a description for every parameter.

guardian_record was called guardian_receipt before 0.5.1. The old name is no longer listed but still works, so existing clients keep running.

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

Only a call whose recorded status is sent-verified is returned as a plain result. Every other outcome is an MCP tool error (isError: true) that says what happened:

  • DENY, or Guardian could not be reached: nothing was done. A denial says not to retry the same call; an outage says to try again later.

  • Status not-sent: outcome: "not-done", the call was not done.

  • Status outcome-pending or outcome-unconfirmed, or an execute answer that was refused or lost: outcome: "unknown". The call may have been done, so check (guardian_record, or the target system) before retrying.

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": "gak_…",
        "GUARDIAN_CONNECTION_ID": "pcn_…",
        "WHATSAPP_TOKEN": "…"
      }
    }
  }
}

Decision

What happens

ALLOW

The call is forwarded to the upstream server, then the capability is redeemed and the signed record kept. The upstream result is returned unchanged, with Guardian's requestId under _meta["com.odingard/guardian"], so the client can fetch the record with guardian_record.

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 result is an MCP tool error (isError: true) with the reason code and, when Guardian made a record of it, the requestId.

Guardian unreachable

Nothing is forwarded. The result is a tool error (isError: true) whose JSON keeps decision: "DENY" with reasonCode: "SERVICE_UNAVAILABLE", and its message says Guardian could not be reached and the call can be tried again later. A held call stays held, so guardian_claim can be retried.

  • guardian_claim and guardian_record are added to the tool list, with the same annotations as above. Here guardian_claim forwards the held call to the upstream server.

  • 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, and it only works for a tool that has no entry yet. An "already registered" answer is refused (RECORD_TRANSPORT_UNVERIFIED) and nothing is forwarded, including after a proxy restart for an entry the proxy created itself. Once the entries exist, run the proxy without it.

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

  • Cancelled requests are not forwarded. If the client cancels a tools/call (or it times out) before the call is sent upstream, for example while Guardian is still deciding, the call is not forwarded and the capability is not redeemed. A guardian_claim cancelled that way keeps the call held with its approval, so the next guardian_claim forwards it without asking the person again. Once a call has been sent upstream it runs to its real outcome, which is recorded.

  • A second guardian_claim of the same requestId says the call was already forwarded and must not be proposed again. If the first claim has finished, its result is returned again after that notice; if it is still running, the answer says to check guardian_record. The proxy remembers the last 1000 claimed requests. A requestId it does not hold is answered with "this claim forwarded nothing", and a reminder to check guardian_record if it was claimed before.

  • An unexpected proxy error after a call was forwarded says the call may have run, never that it was not forwarded.

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

Pin the contents of file arguments: --pin-file (0.4)

Approval binds the exact arguments. A file path is an argument; the file's contents are not, unless you declare the argument with --pin-file.

guardian-mcp proxy --pin-file upload_file:path --pin-file send_email:attachment -- npx -y my-mcp-server

For each declared <tool>:<argument> the proxy (the SDK on your machine) reads the file the path names, puts its SHA-256 in the approved arguments, and checks it again just before the call is forwarded. Guardian's servers never see the file. If the file changed, nothing is forwarded, the capability is not redeemed, and the result says CONTENT_CHANGED_SINCE_APPROVAL; propose the call again for a new approval. A call held for approval keeps the arguments that were proposed, pins included, and guardian_claim checks the file against them. After a proxy restart a claim finds nothing; call the tool again, which pins the file again. The upstream server receives the approved arguments without the reserved key guardianContentPins. In code: createGovernedProxy({ ..., pinFiles: { upload_file: ["path"] } }).

  • The mode is always recheck: the upstream server opens the path itself, so a short window remains between the check and its open. Elsewhere in the SDK bytes is the default when no mode is named; the proxy cannot hand an upstream server bytes, so --pin-file and pinFiles take no mode and always mean recheck.

  • Stdio upstreams only. With --url (HTTP or SSE) the path names a file on another machine, so --pin-file is refused at start (CONTENT_PIN_REMOTE_UPSTREAM). Paths on a remote MCP server are not pinned.

  • File paths must be absolute. The proxy does not resolve relative paths or ~.

  • Content pinning is supported on Linux and macOS. On Windows a declared file argument is refused (CONTENT_PIN_UNSUPPORTED_PLATFORM).

  • Digest privacy: the SHA-256 of each pinned file is sent to Guardian, shown to the approver and kept in the signed decision record. For a small or low-entropy file (a token, a PIN, a short config value), anyone who sees the digest can guess the contents offline by hashing candidates. Do not pin files like that, or treat the digest as sensitive as the file.

  • This stops a changed file from running under an approval given for different contents. It does not protect against code that bypasses the proxy, and files a tool opens without naming them in a declared argument are not pinned.

Dollar amounts on tools: --amount-arg (0.5)

If the owner set a dollar amount on a tool in the Guardian console (which argument holds the amount, cents or dollars), give the proxy the same declaration:

guardian-mcp proxy --amount-arg purchase=amount:minor -- npx -y my-shop-mcp-server

<argument>:minor means cents (2000 is $20.00), <argument>:major dollars (20 or "19.99"); the currency is US dollars. For a currency argument or an "allowed arguments" list, give the declaration as JSON, exactly as in the console:

guardian-mcp proxy \
  --amount-arg 'purchase={"argument":"amount","unit":"minor","currency":"usd","allowedArguments":["amount","sku"]}' \
  -- npx -y my-shop-mcp-server

Each call of that tool carries the declaration and the amount the proxy reads, and Guardian decides on the amount: allow up to the limit, hold for a person above it (guardian_claim forwards the call once after approval), block above the maximum. A call whose amount cannot be read, or whose declaration is not the owner's, is refused and nothing is forwarded. In code: createGovernedProxy({ ..., amountArgs: { purchase: { argument: "amount", unit: "minor", currency: "usd" } } }).

  • The upstream MCP server runs the tool, so the limit applies to Guardian's decision. The proxy forwards the arguments Guardian decided on.

  • Guardian reads one argument. By setting it, the owner states that this argument sets the charge; other arguments that change it (a quantity, a tip) are not seen. An allowed-arguments list blocks calls with any other argument. Without a currency argument, the owner also states that the tool charges in US dollars; Guardian can't check that.

  • One upstream server is one connection, and every tool on a connection needs an amount (or none does). A server that also lists tools without an amount (a search, a list) can't get a dollar limit; put tools that spend money on their own connection.

  • A malformed --amount-arg, an invalid declaration or two declarations for one tool are refused at start, with a message that says what to fix.

  • Works with stdio and remote (--url) upstreams.

Govern a remote MCP server: guardian-mcp proxy --url (0.3.3 and later)

The proxy can also front an MCP server that runs online, such as Composio. The agent still starts guardian-mcp over stdio like any local server; guardian-mcp connects to the remote server over Streamable HTTP (the default) or SSE (--transport sse). Before relying on a remote server, check that its key header is accepted and that a call on an Ask connection waits for approval.

{
  "mcpServers": {
    "composio-governed": {
      "command": "guardian-mcp",
      "args": [
        "proxy",
        "--url",
        "<the URL Composio's generate step returned>",
        "--header",
        "x-api-key: ${COMPOSIO_API_KEY}"
      ],
      "env": {
        "GUARDIAN_BASE_URL": "https://guardian-api.odingard.com",
        "GUARDIAN_AGENT_CREDENTIAL": "gak_…",
        "GUARDIAN_CONNECTION_ID": "pcn_…",
        "COMPOSIO_API_KEY": "…"
      }
    }
  }
}

A server that takes a Bearer key: --url https://mcp.example.com/mcp --header 'Authorization: Bearer ${REMOTE_MCP_API_KEY}'.

  • Every tools/call is decided by Guardian exactly as for a stdio server: ALLOW forwards it, ASK holds it for guardian_claim, DENY never sends it. tools/list passes through, with guardian_claim and guardian_record added.

  • Secrets stay in the proxy. Write header values as ${ENV_VAR}; guardian-mcp expands them itself, so no shell is needed and the key never appears in the agent's view. In a shell, use single quotes so the shell does not expand it onto the command line. The URL and header values are never printed; error messages show the server's origin only.

  • ${…} can only name a variable that is set, and never a GUARDIAN_* one, so the agent credential cannot be sent to the remote server.

  • The URL must be https://; plain http:// is accepted only for localhost. User names or passwords in the URL are refused; send credentials as headers. Redirects to another origin are not followed.

  • Fails closed. If the remote server cannot be reached or rejects the key at startup, guardian-mcp exits with a one-line message and serves no tools. If the remote fails after Guardian allowed a call, the result is an error that says the call may or may not have run, and the capability is not redeemed. It is never reported as a success.

  • guardian-mcp tools --url … lists a remote server's tools with suggested modes, the same as for a local one.

  • OAuth sign-in flows are not supported; use an API key or bearer token header.

  • The upstream cannot speak for Guardian. A remote server's result is passed to the agent as the server's own output, whatever fields it carries. A result that contains a guardian: {decision, requestId} field is never read as a Guardian decision, so it cannot hold, swap or hide a call.

  • If tools/list fails upstream, the agent gets a generic "tool list is unavailable" error. The upstream's error text (which can quote its URL path, response body or headers) is not shown to the agent or logged; guardian-mcp tools --url prints it with the URL, its path identifiers, query values and header values scrubbed. Each query value is scrubbed as typed (a + stays a +), percent-decoded, and with + read as a space.

What is not governed: a remote server the agent connects to directly (for example an MCP client's own "url" entry, or a model provider's hosted MCP connector), and anything the agent does without MCP. Also not covered:

  • Lost results after ALLOW. If the remote times out (the MCP SDK's default request timeout is 60 seconds) or drops the session after Guardian allowed a call, the call may have run, but the capability is not redeemed and no execution record is written. Guardian's records can then understate what happened; check the remote system itself.

  • Keys in the same process tree. guardian-mcp keeps the upstream key out of the agent's MCP view. It cannot stop other code that runs as the same user, in the same container, from reading the key from the environment it was set in and calling the remote server directly. Recipes: ZeroClaw and your own container (CrewAI, LangGraph, AutoGen). Runnable example: examples/mcp/remote-mcp.mjs (fails closed with no settings, runs against Guardian with Guardian settings). --url is in the published @odingard/guardian-mcp from 0.3.3.

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        "write" may change something
delete_branch   Ask me        server marks it destructive
createIssue     Ask me        "create" may change something  ⚠ name not accepted by Guardian

How the suggestions are made:

  • A tool the server marks destructive (destructiveHint) suggests Ask.

  • So does a tool whose name contains a verb that changes something or sends data out, anywhere in the name (create, update, delete, replace, send, run, write and similar), even when the server marks it read-only. get_or_create_customer, find_and_replace and list_and_delete_old_files suggest Ask.

  • Otherwise a tool the server marks read-only (readOnlyHint) suggests Allow, and so does a name that starts with a read verb (get, list, search, read, describe, show, view, find, lookup, count, inspect).

  • Everything else suggests Ask, including fetch (it can send data to any URL) and status.

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.

Available Tools

3 tools
guardian_claimRun an approved requestA
Destructive

Run a request that guardian_invoke_tool held as ASK, once the person has approved it in Guardian. Guardian issues the capability and runs the approved call with its original arguments (it can change the target system), then returns ALLOW with the execution record. Before approval it returns ASK again and runs nothing; a denied, expired or unknown requestId returns DENY with a reasonCode; Guardian unreachable fails closed (SERVICE_UNAVAILABLE) and can be retried. An approval is used once: claiming the same requestId again does not run the call a second time.

Inputs: requestId (required).

guardian_invoke_toolRun a tool through GuardianA
Destructive

Run a tool registered on a Guardian connection, instead of calling it directly. Guardian's rules decide ALLOW, ASK or DENY before anything runs. ALLOW runs the tool at once (it can change the target system) and returns the decision, requestId and execution record. ASK runs nothing and returns a requestId: wait for the person to approve it in Guardian, then call guardian_claim. DENY, or Guardian unreachable (reasonCode SERVICE_UNAVAILABLE), runs nothing; each call is a new request, so after an unknown outcome check guardian_record before calling again.

Inputs: toolName (required), purpose, arguments, connectionId.

guardian_recordGet the records for a requestA
Read-onlyIdempotent

Look up the evidence records Guardian holds for one request, to see what was decided and whether the call ran. It changes nothing and runs no tool, so calling it again is safe. Returns the requestId and its list of records; an unknown requestId, or Guardian unreachable, returns ok: false with a reasonCode. Use it after an unknown or unclear outcome, before trying a call again.

Inputs: requestId (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 3 tools

    Disambiguation4/5

    Each tool has a distinct role: guardian_invoke_tool is the entry point for governed calls, guardian_claim executes an already-approved ASK request, and guardian_record is a read-only audit lookup. The claim/invoke boundary is slightly subtle because both can run a tool, but the descriptions clearly distinguish initiation from approval execution.

    Naming Consistency5/5

    All tools use the guardian_ prefix and snake_case, with predictable verb-oriented names (claim, invoke_tool, record). The convention is consistent throughout and easy to scan.

    Tool Count5/5

    Three tools are well matched to a narrowly scoped governance/approval wrapper: one to invoke, one to claim an approval, and one to inspect records. No tool feels redundant or missing for this purpose.

    Completeness4/5

    The surface covers the key decision lifecycle: invoke, defer to approval, claim after approval, and inspect evidence afterward. A minor gap is the lack of an explicit pending-request listing, though the external Guardian UI plausibly handles that workflow.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Security gateway that wraps any MCP server with per-tool policies, approval gates, and optional Ed25519-signed decision receipts. Shadow mode logs every tool call without blocking; enforce mode applies block, rate-limit, and minimum-tier rules. Receipts are independently verifiable offline with no accounts needed.
      5
      11
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Wraps your existing MCP servers and checks each tool call against policy and live state before it runs. Allow, block, or require a refresh, with a reason the agent can act on.
      5
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Sits in front of any MCP server to enforce allow/ask/block policies on tool calls, paths, shell commands, and network domains, with local approval prompts and an audit log.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides a governance layer for MCP servers, enforcing policy-based allow/deny/approval rules, requiring human approval for risky calls, and recording an auditable trail of every AI agent tool call.
      MIT