MCP Approval Queue

@opafex/mcp-approval-queue

A human-in-the-loop approval gate for AI agents, as an MCP server.

The agent calls request_approval before doing something risky. The action is risk-scored, and unless a rule you set covers it, you decide — in a form your MCP client shows you (MCP elicitation), or from a terminal. The agent gets a proceed: true|false it can act on.

The agent can ask; only a human can approve. There is no approve, reject or add-rule tool for the model to call. An approval gate the gated agent can open is not a gate.

Requires Node.js 20+.

Quick start

Add to your client's MCP config (for Claude Code, .mcp.json in your project root):

{

"mcpServers": { "approval-queue": { "command": "npx", "args": ["-y", "@opafex/mcp-approval-queue"] } } }

Then tell the agent when to use it, for example in your project instructions:

Before deleting data, sending email, spending money or deploying, call request_approval and only continue if proceed is true.

How a request is decided

1. Risk is scored from the action name — bulk_delete_users is a delete wherever the word sits — plus params.estimatedCost. The agent may pass a category, but it can only raise the score, never lower it.
2. A rule may auto-approve it — only low or medium risk, only rules a human created. High and critical risk always go to a person.
3. Otherwise a person decides:

• In the client — if the client supports elicitation, the server asks you directly with the action, risk, parameters and the agent's reason, and waits for your answer. The answer goes to the server, not to the model. Approve, reject, or tick *Always approve* (low/medium risk only) to create a rule. Dismissing the form leaves the request pending.
• In a terminal — otherwise the request waits, and the agent is told to poll check_status:

bash npx @opafex/mcp-approval-queue pending npx @opafex/mcp-approval-queue approve appr_3f9c1a2b4d5e --reason "checked the recipient list" npx @opafex/mcp-approval-queue reject appr_3f9c1a2b4d5e

1. Unanswered requests expire after 24 hours (APPROVAL_QUEUE_TTL_HOURS) and can no longer be approved.

After five human approvals of the same action with no rejection, the next form suggests *always approve*. Auto-approvals do not count towards that — the system agreeing with itself is not evidence.

Tools (what the agent sees)

status is one of pending, approved, rejected, auto_approved, expired. Proceed only when proceed is true.

Resources

CLI

mcp-approval-queue                       start the MCP server (stdio)

mcp-approval-queue pending list requests waiting for a decision mcp-approval-queue show one request in full mcp-approval-queue approve [--always] [--reason ] mcp-approval-queue reject [--reason ] mcp-approval-queue rules list rules mcp-approval-queue rules add --max-risk [--description ] mcp-approval-queue rules remove mcp-approval-queue history [limit]

Patterns are globs: * matches anything, ? one character, case-insensitive. A rule can never cover high or critical risk.

Configuration

State is one JSON file, written atomically under a lock file, so the server and the CLI can run at the same time.

What it does not protect against

Be clear about this before relying on it:

• An agent with a shell or file access can reach the terminal channel. The CLI and state.json are a human channel only if the agent cannot run the command or write the file. Coding agents such as Claude Code usually can. In that setup rely on the elicitation channel, and deny the agent the CLI and the state directory in your client's permission settings — for Claude Code, deny Bash(npx @opafex/mcp-approval-queue approve:*), Bash(npx @opafex/mcp-approval-queue rules:*), and edits under ~/.opafex/.
• It only gates what the agent asks about. The agent has to call request_approval, and has to honour proceed: false. This is a protocol for a cooperative agent and a record of what was allowed, not a sandbox. Pair it with your client's own tool permissions for anything that must be enforced.
• Elicitation is shown by the client. The guarantee that the answer came from a person is only as good as the client's rendering of the form.

Library use

import { ApprovalQueueService, StateStore, assessRisk } from '@opafex/mcp-approval-queue';

const queue = new ApprovalQueueService(new StateStore('/var/lib/my-app/approvals')); const { request } = await queue.requestApproval({ action: 'refund_order', params: { estimatedCost: 40 } });

Development

npm install

npm run build npm test

License

MIT — see LICENSE.