Approval Gate MCP

approval-gate-mcp

An MCP server and library for requesting a human decision before a consequential agent action. Approvals expire, are single-use and can bind an operation to an exact payload.

The trusted executor must enforce the approval. Installing an MCP server does not prevent an agent from using another tool, and the gate is not a security boundary against processes with the same OS-user privileges. Read the trusted execution boundary and threat model before integration.

Release and verification

As of 31 October 2026, v0.4.1 on GitHub and 0.4.1 on npm are published. Source changes, GitHub releases and registry publication are separate states; these links identify the released version.

Requires Node.js 22+. See the MIT license, changelog and test suite. The 0.4.1 release notes describe the shipped changes. Tests apply to the revision and environment where they ran; they do not establish production certification. The quickstart below pins the published package; run npm test for your own checkout.

Why

Sending, deleting, publishing, spending and deploying need a decision tied to the actual operation. A general instruction to "ask first" leaves the executor to interpret an informal conversation. This project records a specific request, a human decision, an expiry and a single-use consume step that trusted execution code can enforce.

Use it when you control that execution boundary. If an agent can bypass it through a shell, another tool or direct file access, adding this server alone cannot enforce approval.

30-second quickstart

claude mcp add approval-gate -- npx -y @itcustomsolution/approval-gate-mcp@0.4.1

Claude Desktop (claude_desktop_config.json):

{

"mcpServers": { "approval-gate": { "command": "npx", "args": ["-y", "@itcustomsolution/approval-gate-mcp@0.4.1"] } } }

Approve or deny from your terminal with npx -p @itcustomsolution/approval-gate-mcp@0.4.1 approval-gate list.

Example

1. Your agent wants to email a customer. It calls request_approval with action: "send email to alice@example.com, subject: Invoice 1042" and gets back id a1b2c3d4e5f6.
2. It calls wait_for_approval. Nothing is sent.
3. In your own terminal: approval-gate list, then approval-gate approve a1b2c3d4e5f6 looks right.
4. The agent can observe approved, but that status does not authorize sending. The trusted executor calls executeApproved for that id and the exact action (plus operation/payload binding, if present) immediately around its send function. See Trusted execution boundary. It must not accept an agent-supplied or MCP JSON result as proof. Denial, timeout or expiry prevents a successful consume.
5. ~/.approval-gate/audit.jsonl now has the request and your decision.

Design principles

• Fail closed. The only thing that authorizes an action is a successful consume: consume_approval returning ok: true (once, for the exact approved action), or executeApproved in trusted code. Pending, approved-but-not-consumed, denied, expired, timeout, error: none of those is an authorization; all of them mean no.
• The gate never executes anything. It records intent and decisions. Your agent asks first, then acts only on approval. Separation of decision and execution keeps the gate simple and auditable.
• Decisions are out-of-band. A human approves or denies with a CLI in their own terminal, not inside the agent's context. The MCP tools cannot approve. The CLI asks for an interactive terminal and a re-typed confirmation, which is a speed bump, not authentication: anything running as your OS user (a shell, a PTY, or file access) can still get past it. See Threat model.
• Only a consume authorizes. status: "approved" is informational. Status responses carry authorizesExecution: false and an effectiveStatus (approved_unconsumed, approved_expired, consumed, revoked, ...). Trusted code that performs the side effect should call executeApproved (see Trusted execution boundary), which consumes the approval itself. A consume result that arrived over MCP, from a file or from an agent is never proof of approval, however well-formed.
• Everything is audited. Every request, decision, expiry, and consumption is appended to ~/.approval-gate/audit.jsonl (an append-only convention, not a tamper-proof log).
• Requests expire. Default TTL is 1 hour; a stale approval is not an approval.
• Approvals are single-use and bound to the action. consume_approval succeeds once, only for the exact action text that was approved (and, if the request carried them, the same operation name and the same canonical JSON payload), and only if the clock read after all of its persistence is still at or before the request's expiry.

Install

Requires Node.js 22 or later (Node 18 and 20 are past end of life; the MCP SDK's @hono/node-server dependency needs Node 20+).

From npm:

npm install -g @itcustomsolution/approval-gate-mcp@0.4.1   # installs `approval-gate` and `approval-gate-mcp`

From source:

git clone --branch v0.4.1 --depth 1 https://github.com/itcustomsolution/approval-gate-mcp.git

cd approval-gate-mcp npm ci --ignore-scripts npm test # builds the source and runs the tests node dist/cli.js list

Wire it into an MCP client

Claude Code:

claude mcp add approval-gate -- node /path/to/approval-gate-mcp/dist/index.js

Or in any MCP client config:

{

"mcpServers": { "approval-gate": { "command": "node", "args": ["/path/to/approval-gate-mcp/dist/index.js"] } } }

Tools

The human side

approval-gate list                # pending requests

approval-gate show a1b2c3d4e5f6 approval-gate approve a1b2c3d4e5f6 looks right, ship it approval-gate deny a1b2c3d4e5f6 wrong recipient approval-gate revoke a1b2c3d4e5f6 changed my mind # approved but not yet consumed approval-gate list approved --limit 20 --after a1b2c3d4e5f6 # page through history approval-gate archive --older-than-days 30 # retention: move finished requests aside

show and the approve confirmation print the operation and the full canonical payload (escaped) when a request binds one: that is exactly what an executor will be allowed to run.

Suggested agent policy

Put something like this in your agent's system prompt or policy file:

Before any outbound or destructive action (send, publish, delete, purchase, deploy),

call request_approval and then wait_for_approval. When it returns approved, call

consume_approval with the same id and exact action text, and proceed only if it returns

ok: true. Never call decide_approval for your own requests.

Trusted execution boundary

When your own code (not the agent) performs the side effect, let the gate consume the approval at that boundary and run exactly the approved payload:

import { executeApproved } from "@itcustomsolution/approval-gate-mcp/dist/store.js";

// id comes from the agent; the action, operation and payload are what your code is about to run. await executeApproved(id, { action, operation: "smtp.send", payload: { to, subject, body } }, async (ctx) => { ctx.assertActive(); // re-check expiry immediately before the side effect await smtp.send(ctx.payload); // ctx.payload is a frozen copy of what the human approved });

executeApproved accepts no receipt. It performs the single-use consume itself (binding to the action text, and to the operation and payload if the request carried them), writes an execution_started audit line (fsync), checks expiry again, and only then calls your function. If the start record cannot be written, or the approval expired during that write, nothing runs. Call ctx.assertActive() again after any await that precedes the side effect.

assertConsumed(result, id, action, binding?) remains for code that calls consumeApproval itself: it accepts only a grant object issued by consumeApproval in the same process, once, for the same id/action/binding, before expiry. A copy, a JSON round trip (an MCP response, a file, an agent message) or a hand-built object is always refused. 0.3.0 accepted any well-shaped object; see the changelog.

Crash and replay semantics. Consumption is at-most-once: once .used is claimed the approval is spent, whatever happens next, including refusals after the claim (expired during persistence, audit failure). A crash after execution_started and before execution_finished means the outcome is unknown: inspect the external system and, if needed, create and approve a new request. Nothing is retried automatically, and there is no atomic guarantee between this gate's files and the external system your callback touches. Details: docs/authorization-states.md.

Limits

When the queue is full, request_approval fails with approval queue full until a human decides requests or they expire. Finished requests stay on disk until you run approval-gate archive, which moves only finished requests that were created and expired at least 8 days ago, so nothing archived can still be used. An MCP client can create and deny its own requests without a human, so it can fill requests/ up to the creation limit; that blocks new requests (an availability limit, like the queue cap), never a human's decisions. Each listing page reads every request file, so listing slows down as history grows until you archive. Paginated listing streams directory entries