MCP server tool call approval: gating an agent's tools
How to gate an MCP tool call: @duereason/mcp's request_approval and wait_for_approval tools, the signed grant they return, and today's install caveat.
Updated · 8 min read
In short
- An MCP client can call a destructive tool the moment the model decides to, so a blanket allow or deny on a tool name is the only brake most setups have today.
- @duereason/mcp adds two MCP tools, request_approval and wait_for_approval, that an agent calls before the consequential tool call: the agent asks through DueReason, the organization's workflow decides who answers, and the agent gets back the decision and, when approved, a signed grant to hand to whatever executes the action.
- The grant is single-use and bound to the exact payload approved, so the executor -- not the agent's say-so -- is what actually permits the action.
- Five more tools -- create_action, update_action, create_workflow, update_workflow, delete_workflow -- let an agent (or a person driving one through setup) provision the action and approval rule themselves instead of using the console, gated on the action:manage scope.
- @duereason/mcp is published to npm, so the install commands below resolve today.
An MCP client doesn't ask permission before it calls a tool -- the model decides, and the tool call runs. For a read-only tool that's fine. For one that pays an invoice, deploys to production or deletes data, the only brake most setups have is a blanket allow or deny on the tool's name, decided once, in advance, with no view of what this particular call is about to do. @duereason/mcp puts a request in front of exactly those calls: the agent asks, a person decides, and the agent gets back a signed, payload-bound grant before it (or whatever executes on its behalf) proceeds.
What the server adds
@duereason/mcp (source: duereason/mcp/src/server.ts, entry point duereason/mcp/main.ts) is an MCP server an agent connects to like any other: over stdio for a single client (Claude Code, Claude Desktop, Cursor), or as a shared HTTP service for a team or a fleet of agents and CI pipelines. It registers tools in a few groups:
- Ask and wait.
request_approvalfiles the request (action, title, reason, payload, optional context links and file attachments);wait_for_approvalandget_approvalpoll or long-poll an existing request for its decision;cancel_approvalwithdraws a pending one;list_approvalsfinds requests already filed, by status, action or free text. - See what would happen before asking, or provision it yourself.
list_actionsandget_actionshow which actions need approval and the payload each expects;list_workflowsandget_workflowshow the approval rules configured for the organization -- conditions, auto-approve, who must approve when not -- so an agent (or the person configuring it) can see how a request would route before filing one.create_action,update_action,create_workflow,update_workflowanddelete_workflowgo further: they let an agent (or a human driving one) register the action and the approval rule that governs it, the same setup the console's action and workflow editors do, gated on theaction:managescope. - Report, audit and verify.
report_executiontells DueReason the grant was used and with what outcome, which is what makes a grant single-use;get_receiptandlist_receiptsreturn the signed, portable record of a decided request;get_ledger_headreports whether the organization's tamper-evident decision ledger still verifies intact. - Mandates and precedent.
list_mandates,get_mandate,revoke_mandateandcheck_mandatecover standing, bounded, revocable authority an agent can act under without asking every time;get_precedentsandcheck_precedentssurface similar past decisions and why they were made -- informational, never a decision by themselves. - Comments.
list_commentsreads the discussion thread on a request -- the same thread console users see. - Webhook management, gated on the
webhook:manageAPI-key scope:list_webhook_endpoints,get_webhook_endpoint,create_webhook_endpoint,update_webhook_endpoint,delete_webhook_endpoint,rotate_webhook_secret,list_webhook_deliveries,send_webhook_testandredeliver_webhook_delivery.
Every tool's description and result tells the connected model the rules directly: ask before doing anything consequential, never perform the action unless the status is approved, pass the grant unchanged to whatever executes it, and report the outcome once it has. A rejection's comment is read as the people's answer -- the tool descriptions tell the model not to retry the same request hoping for a different one.
A worked example: gating a production deploy
DueReason ships a deployment action template (duereason/core/src/approval-templates.ts, template id production-deploy) whose payload is service, environment (staging or production), commit, and optionally changeSummary and pullRequestUrl; its default workflow auto-approves staging and routes production through an engineering lead and then security. An agent with a deploy tool calls request_approval instead of running it directly:
``json { "action": "deployment", "title": "Deploy billing-service to production", "reason": "PR #482 merged to main; ships the Q4 invoicing fix.", "payload": { "service": "billing-service", "environment": "production", "commit": "a1b2c3d", "pullRequestUrl": "https://github.com/acme/billing-service/pull/482" }, "wait_seconds": 300, "idempotency_key": "deploy-billing-service-a1b2c3d" } ``
With wait_seconds set, request_approval blocks (sending MCP progress notifications every 15 seconds so a client that resets its timeout on progress doesn't give up) until the request is decided or the timeout passes, and returns the final status either way; without it, the agent calls wait_for_approval (or get_approval) afterward to keep waiting, at up to 600 seconds per call. idempotency_key is there so a retried call after a dropped connection reuses the same request instead of filing a duplicate -- 1 to 200 characters, matching the same mechanism the TypeScript SDK exposes as idempotencyKey. Once the engineering lead and security both approve, the tool's result carries the decision and a signed grant bound to exactly this payload; the deploy pipeline that actually runs git push, not the agent's say-so, verifies that grant (verifyGrant from @duereason/sdk) before it acts, then calls report_execution once with the outcome. A second report_execution for the same grant answers already_executed -- that, not the agent's good behavior, is what stops one approval from deploying twice.
Provisioning workflows via MCP
The worked example above assumes the deployment action and its workflow already exist. create_action, update_action, create_workflow, update_workflow and delete_workflow let an agent (or a human driving Claude Code, Claude Desktop, Cursor or Hermes through the connected server) set that up itself instead of using the console's action and workflow editors -- useful for an agent bootstrapping its own approval gate as part of its own setup, or for someone who would rather describe the gate in a chat than click through a form. All five require the action:manage scope on the API key, on top of whatever the read or request tools above need.
A minimal sequence to gate a new kind of request, a host restart, from scratch:
``json // 1. create_action -- register what can be asked for { "key": "server-restart", "name": "Restart a production server", "description": "An agent asking to restart a host it manages.", "payloadSchema": { "type": "object", "properties": { "host": { "type": "string" }, "reason": { "type": "string" } }, "required": ["host", "reason"] } } ``
``json // 2. create_workflow -- decide who must approve a request for it { "action_key": "server-restart", "name": "On-call approves every restart", "definition": { "conditions": [], "autoApprove": false, "steps": [ { "name": "On-call approval", "required": 1, "evidence": "text", "groups": ["grp_oncall"], "users": [] } ] } } ``
From there, request_approval against the server-restart action routes to the on-call group exactly as it would for a workflow built in the console. update_action and update_workflow change an existing one the same way (fields left out keep their current value, though update_workflow's definition replaces the whole thing at once -- there is no way to patch a single condition or step); delete_workflow removes a rule for good, with no undo, and a deleted workflow's past decisions are unaffected -- create a new one with create_workflow to resume routing the action.
None of this changes who decides a live request. Creating an action and a workflow only shapes what request_approval can later ask for and whether a human looks at it at all -- it does not itself approve, reject or execute anything, and no individual request skips the signed-grant path described below because it was provisioned over MCP rather than in the console. The one way a workflow stops asking a human per request is autoApprove: true on its definition, available to create_workflow/update_workflow the same as it is in the console editor -- and turning it on through the API emails the organization's owners and posts to any subscribed Slack/Teams channel, so it is not a silent way for an agent to grant itself a rubber stamp.
The grant model
In the MCP server's own words: "The agent asks through DueReason, the organization's workflow decides who answers, and the agent gets back the decision and, when approved, a signed grant to hand to whatever executes the action." And: "the grant it gets back is single-use and bound to the exact payload approved." Nothing about that changes because the request came in over MCP rather than the SDK or the console API directly -- a grant from request_approval is the same signed, offline-verifiable token described in verifying a grant without Node, checked against the organization's published JWKS, naming the action and a hash of the approved payload, and expiring if nobody picks it up.
Attachments and scopes
request_approval accepts up to 5 files ({ filename, contentBase64 }, 10 MB raw each), attached the way the console does: scanned, hashed and bound into the signed receipt -- the invoice, the terraform plan, the change-risk document an approver needs to decide. The API key behind the MCP connection needs the action:read, approval:request and approval:read scopes for everything above the webhook tools; add webhook:manage only if the agent (or the person operating it) also needs the webhook endpoint tools, or action:manage if it also needs to create, update or delete actions and workflows (create_action, update_action, create_workflow, update_workflow, delete_workflow).
Installing it today
@duereason/mcp is on npm: npx -y @duereason/mcp resolves today. Connecting it is one line for Claude Code (claude mcp add duereason --env DUEREASON_API_KEY=pk_live_... -- npx -y @duereason/mcp), a few lines of JSON for Claude Desktop or Cursor, or, for a team or a fleet of agents, one @duereason/mcp process run with DUEREASON_MCP_TRANSPORT=http, each client authenticating with its own bearer token rather than sharing one key.
Questions
- Does the agent decide whether its own tool call is approved?
- No. The agent only files the request (request_approval) and waits (wait_for_approval); the decision is made by whoever the organization's workflow routes it to, the same four-eyes model as any other DueReason request. The agent cannot approve its own request.
- Does creating an action or workflow over MCP approve or auto-approve anything?
- No. create_action, update_action, create_workflow, update_workflow and delete_workflow only define what request_approval can later ask for and who (if anyone) must decide it; they require the action:manage scope, separate from the approval:request/approval:read scopes that file and read requests. A workflow can still be set to autoApprove: true, the same setting the console's editor exposes, but turning it on emails the organization's owners and posts to any subscribed Slack/Teams channel, so it isn't a silent way for an agent to skip human review.
- What stops an agent from just skipping request_approval and calling the real tool directly?
- The MCP server itself doesn't stop that -- it only adds the ask-first tools. What has to refuse is the target that performs the action: a deploy pipeline or payment executor that checks for a valid, matching grant before it acts. That target-side check, not the agent choosing to ask nicely, is what actually gates the call; see the agent-gate guide for the two-layer model this follows.
- Can I install @duereason/mcp today?
- Yes. The package is published to npm, so npx -y @duereason/mcp resolves and installs it. See Install above for Claude Code, Claude Desktop, Cursor and a shared HTTP server setup.
- Is the grant returned over MCP any different from the one the SDK or console produce?
- No. It is the same signed, payload-bound, single-use grant described in the API reference and in the grant-verification guide, regardless of whether the request was filed through the MCP server, the TypeScript SDK, or the console API directly.
- What happens if the MCP client gives up waiting before a decision is made?
- The request keeps going on DueReason's side -- waiting does not cancel it. Call get_approval (or wait_for_approval again) with the request's id to keep checking; only cancel_approval withdraws it.
See every MCP tool and its parameters
The full request/response shape for request_approval, wait_for_approval and every other tool @duereason/mcp exposes lives in the API reference.
Read the API docsSources
This guide explains the regulation as we read it; it is not legal advice. Check the official text and your national law, which may add obligations.