Skip to main content
Glama

mcp-guardrails

An MCP server that puts a policy layer and an append-only audit trail in front of the tools an AI agent is allowed to call.

The useful question about an agent integration is rarely "can it call the API?" — it's what is it allowed to do, what is it not, and can you prove afterwards what it did? This server answers those three questions as a reusable layer rather than as conditionals scattered through tool handlers.

agent ──▶ MCP tool call ──▶ [ policy engine ] ──▶ implementation
                                   │                     │
                                   └──────▶ audit log ◀──┘

Every call takes the same path: evaluate, log, then execute or refuse. The implementation is only reachable through the guard closure, so there is no code path that reaches a side effect without passing the policy first.

Why this shape

Capability is data, not code. What an agent may do lives in one JSON file a reviewer can read in a minute. The alternative — permission checks inline in each handler — means the real answer to "what can this agent do?" is spread across a codebase and nobody is certain.

Unlisted means denied. The default decision is deny. Adding a tool to the server does not make it callable; adding it to the policy does. A new tool that someone forgot to think about fails closed.

Three tiers, not two. allow / deny is too coarse for the operations that are legitimate but consequential — closing someone's ticket, writing to a shared branch. Those get confirm: the call is logged with its arguments and refused, so a human can look at exactly what was proposed.

A refusal is not an error. When the policy says no, the agent is told so explicitly, including that retrying will not help. Agents handed a bare failure tend to retry in a loop; being told "this is a policy decision, ask a human to change the policy" ends the loop and gives the model something useful to relay.

The audit log is safe to share by construction. Credential-shaped argument names (token, apiKey, authorization, password, …) are redacted recursively before anything is written. The log is the artefact most likely to end up pasted into a ticket, so it shouldn't depend on the person remembering to scrub it.

Constraints only ever tighten. A constraint can turn an allow into a deny, never the reverse. There is no ordering puzzle where an argument rule accidentally grants access.

Related MCP server: Dvarapala

Quick start

npm install
cp policy.example.json policy.json
npm test          # builds, then runs 45 tests
npm start         # serves over stdio

Point an MCP client at it:

{
  "mcpServers": {
    "guardrails": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-guardrails/dist/src/index.js"],
      "env": {
        "MCP_GUARDRAILS_POLICY": "/absolute/path/to/policy.json",
        "MCP_GUARDRAILS_ROOT": "/absolute/path/to/a/workspace"
      }
    }
  }
}

Variable

Default

Purpose

MCP_GUARDRAILS_POLICY

./policy.json

Policy file. Startup fails loudly if it's missing or malformed.

MCP_GUARDRAILS_ROOT

cwd

Directory the workspace tools are confined to.

MCP_GUARDRAILS_AUDIT

.audit/calls.jsonl

Audit log path, or none to keep it in memory.

MCP_GUARDRAILS_DRY_RUN

off

1 logs and describes mutating calls without executing them.

Writing a policy

{
  "defaultDecision": "deny",
  "rules": [
    { "tool": "issues.list", "decision": "allow" },

    {
      "tool": "issues.comment",
      "decision": "allow",
      "reason": "Commenting is reversible and useful",
      "constraints": { "body": { "maxLength": 2000 } },
      "rateLimit": { "perMinute": 5 }
    },

    {
      "tool": "issues.close",
      "decision": "confirm",
      "reason": "Closing an issue is visible to the whole team"
    },

    {
      "tool": "workspace.write",
      "decision": "allow",
      "constraints": {
        "path": { "pathPrefix": ["src/", "test/"], "pathDeny": [".env", "secret"] },
        "content": { "maxLength": 100000 }
      }
    }
  ]
}

Constraints: maxLength, maxNumber, oneOf, matches (regex source), pathPrefix, pathDeny.

The path check, specifically

Path arguments are normalised before the prefix test. This matters more than it looks:

src/../.env   →  normalises to  .env   →  fails the "src/" prefix rule

A naive path.startsWith("src/") accepts that string, and the consequence is reading a credentials file. Absolute paths and anything climbing above the root are rejected outright. The workspace tools then independently resolve-and-compare against the root, including the trailing-separator check that stops /tmp/root-evil passing for /tmp/root. Two layers, because a prefix rule in a config file is easy to get subtly wrong and the blast radius is secrets.

Tools included

The tools are a realistic demonstration surface; the guard layer is the reusable part. Swapping the in-memory issue store for Jira or Linear means replacing four functions and changing nothing about policy or audit.

Tool

Policy name

Mutating

issues_list

issues.list

no

issues_comment

issues.comment

yes

issues_close

issues.close

yes

workspace_list

workspace.list

no

workspace_read

workspace.read

no

workspace_write

workspace.write

yes

audit_tail

audit.tail

no

audit_tail deliberately exposes the trail back to the agent. An agent that can see why it was refused can explain it to the user instead of silently retrying, and the log is already redacted — there is nothing in it a caller couldn't learn by making the same calls.

Audit format

One JSON object per line, opened in append mode per write — greppable, tail -f-able, survives restarts, and awkward to rewrite after the fact.

{"ts":"2026-11-16T09:08:29.359Z","requestId":"3f2a…","tool":"issues.comment","args":{"id":1,"body":"note"},"decision":"deny","reason":"Rate limit reached for \"issues.comment\": at most 5 call(s) per minute","outcome":"blocked","durationMs":0}

decision is what the policy said; outcome is what happened (ok, blocked, error, dry-run). They're separate fields because "allowed but then threw" and "never allowed" are different failures and you want to tell them apart at 3am.

Tests

$ npm test
# tests 45
# pass 45
# fail 0

Node's built-in runner, no test framework dependency. The clock is injectable, so the rate-limit tests assert window roll-over without sleeping. Coverage worth calling out:

  • unlisted tools fail closed

  • constraints can tighten allow → deny but never loosen a deny

  • a refused call doesn't consume rate-limit budget

  • the src/../.env prefix bypass is rejected

  • a sibling directory doesn't satisfy the root-prefix check

  • credentials are redacted before the sink sees them, verified by asserting the raw secret appears nowhere in the serialised entry

  • a corrupted audit line is skipped rather than throwing

Limitations

Worth stating plainly rather than discovering later:

  • Rate limits are per-process and in-memory. Restarting resets them; two instances don't share a window. Fine for a single stdio server, wrong for a multi-replica deployment — that needs a shared store.

  • confirm has no approval channel. It refuses and records the arguments; wiring it to Slack or a web approval step is integration-specific and deliberately out of scope here.

  • The policy is matched on exact tool names. No globs. Adding them would mean precedence rules, which is exactly the complexity this design avoids.

  • The issue store is in memory. Restarting loses comments. It's a demonstration surface, not a tracker.

Licence

MIT

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables controlled AI-agent access to enterprise-shaped tools with a deny-by-default gated write path, human approval, dry-run execution, and append-only audit logging.
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides permission gates and tamper-evident audit logging for AI agent tool executions, with declarative policies, consent ladders, and hash-chained verification.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enforces deterministic policy decisions on AI agent tool calls, supporting allow, deny, correct, escalate, and human review actions with verifiable audit receipts.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables governed tool-calling agents with policy decisions, optional human approval, hash-chained audit logging, and deterministic evaluation.
      MIT