mcp-safe-actions
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcp-safe-actions: human approval for destructive MCP tools
Your AI agent should not be able to delete a file, send an email or drop a table just because it decided to.
mcp-safe-actions is a small TypeScript library for people who build MCP servers (Model Context Protocol). Wrap a dangerous tool once and it does nothing until a human approves. The model cannot approve its own action.
Why you might want this
A prompt-injected or confused model can call
delete_file("../../important"). "Please ask first" in a prompt is a request, not a control.Approval in the client UI is the right place for a human decision, and MCP now has a feature for it (elicitation). Not every client supports it yet, so you also need a safe fallback.
You want a log of what was previewed, approved, refused and run, without leaking secrets.
This library packages that pattern once, with a test suite that proves the safety rules, instead of rebuilding it in every server.
Related MCP server: mcp-confirm
Add it to your MCP server in 4 steps
1. Install
npm install mcp-safe-actionsPublished on npm: https://www.npmjs.com/package/mcp-safe-actions
You also need @modelcontextprotocol/sdk (1.17+) and zod (you probably have both). Node 18+.
2. Wrap your dangerous tool
Replace server.registerTool(...) with registerConfirmedTool(server, ...) and split the work into preview (describe, don't change anything) and execute (runs after approval):
import { rmSync, statSync } from "node:fs";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import { registerConfirmedTool, fileAudit } from "mcp-safe-actions";
const server = new McpServer({ name: "files", version: "1.0.0" });
registerConfirmedTool(server, {
name: "delete_file",
description: "Permanently delete one file.",
inputSchema: { path: z.string() },
// What WILL happen. Must not change anything. Be specific.
preview: ({ path }) => ({
summary: `Permanently delete "${path}" (${statSync(path).size} bytes)`,
details: ["This cannot be undone."],
}),
// Runs only after the user approved. Re-check anything that could have changed.
execute: ({ path }) => {
rmSync(path);
return { content: [{ type: "text", text: `Deleted ${path}` }] };
},
audit: fileAudit("./audit.jsonl"), // optional
});
await server.connect(new StdioServerTransport());The tool is listed with destructiveHint: true and a description telling the model to wait for the user.
3. Run the demo and the tests
git clone https://github.com/techsaurabh-394/mcp-safe-actions.git
cd mcp-safe-actions
npm install
npm run demo # prints both approval flows
npm test # 101 tests4. Connect it to an MCP client
Claude Desktop (claude_desktop_config.json), using the included example server and a throwaway folder:
{
"mcpServers": {
"files": {
"command": "node",
"args": ["/absolute/path/to/mcp-safe-actions/dist/examples/files-server.js"],
"env": { "FILES_DIR": "/absolute/path/to/test-folder", "AUDIT_LOG": "/absolute/path/to/audit.jsonl" }
}
}
}Claude Code: claude mcp add files -- node /absolute/path/to/mcp-safe-actions/dist/examples/files-server.js
Run npm run build first. Then ask the assistant to delete a file in the test folder. You should see either an approval prompt (clients with elicitation) or a preview with a token and a question from the assistant (clients without). The file must still exist until you say yes.
How it works
Client supports elicitation (best case):
sequenceDiagram
participant M as AI model
participant S as Your MCP server
participant H as Human (client UI)
M->>S: delete_file("report.pdf")
S->>S: preview() builds the plan, nothing changes
S->>H: Approval prompt: delete report.pdf?
H-->>S: Approve or decline
alt Approved
S->>S: execute() and audit log
S-->>M: Deleted report.pdf
else Declined or no answer
S-->>M: User did not approve. Nothing changed.
endClient without elicitation (token fallback):
sequenceDiagram
participant M as AI model
participant S as Your MCP server
participant H as Human (in chat)
M->>S: delete_file("report.pdf")
S-->>M: Nothing changed yet. Plan + one-time token
M->>H: Shows plan, asks to go ahead
H-->>M: Yes
M->>S: delete_file("report.pdf", confirm_token)
S->>S: token valid, unused, same arguments, not expired
S->>S: execute() and audit log
S-->>M: Deleted report.pdfDecision table
Situation | Result |
Elicitation accepted and the box is ticked |
|
Declined, cancelled, unticked, timed out or errored | Nothing runs |
| Refused, no token issued |
Token flow, no token | Preview plus one-time token, nothing runs |
Token flow, valid token and identical arguments |
|
Reused, expired, unknown, or for other arguments or another tool | Nothing runs, reason returned |
Modes
| Behaviour | Use when |
| Elicitation if supported, otherwise token | Most servers |
| Elicitation only | Actions that must have a human gate |
| Always the token flow | Testing, or by preference |
| Asks your | Headless servers with no client UI |
Proof it works: tests that try to break it
101 tests | Unit, end-to-end (a real MCP client and server in memory), property tests (300 random argument objects), and real stdio tests that spawn the example server as a child process |
100% line coverage of the library ( |
|
42 deliberate bugs, all caught |
|
What the tests prove, among other things: a declined prompt never runs the action; a model-supplied token cannot skip the human prompt; tokens are single-use, expire, and only work for the same tool and arguments; two simultaneous uses of one token run the action exactly once; a prompt that times out or crashes fails closed; secret argument values never reach the audit log; the example server blocks path traversal and symlink escapes.
Details and an honest note about a weak test the mutation check caught: docs/TESTING.md.
Guarantees, and what it does NOT guarantee
It guarantees | How |
Nothing runs before approval |
|
The model can't self-approve (elicitation) | The prompt goes to the human through the client, not through the model |
Tokens are single-use, bound to tool and exact arguments, and expire | Checked server-side |
Failures fail closed | Errors and timeouts never fall through to execution |
Audit without leaking secrets | Logs your summary and a hash of the arguments, never the raw arguments |
Be clear-eyed:
Token mode is a speed bump, not proof of a human. A model could call twice without asking. For actions that need a real human gate, use
mode: "elicit".Your preview must be truthful, and
execute()should re-check state that may have changed since.It doesn't sandbox your server. It gates the tools you wrap. Keep least-privilege credentials and validate inputs.
Elicitation depends on the client. Support differs by client and version.
Full threat model: docs/SECURITY-MODEL.md.
API
registerConfirmedTool(server, {
name, title?, description, inputSchema, // like server.registerTool
preview(args) => { summary, details? }, // no side effects
execute(args) => CallToolResult, // after approval
risk?: "destructive" | "write", // default "destructive" (sets annotations)
mode?: "auto" | "elicit" | "token", // default "auto"
approvalTimeoutMs?: number, // default 5 minutes; a timeout means "not approved"
approver?: (req) => boolean | Promise<boolean>, // required for mode "channel"
resolve?(args) => { label?, role?, url?, ... }, // optional: look up what the call actually targets, before the policy runs
pinFields?: string[], // optional: which resolved fields must be unchanged right before execute (default: all)
gate?: { pattern: RegExp, fields?: string[] }, // optional: if the resolved context matches, autoApprove is skipped
autoApprove?(args, plan, context) => boolean, // optional: exactly `true` skips the prompt for low-risk calls
store?: new ApprovalStore({ ttlMs, maxPending }),
audit?: (event) => void | fileAudit(path),
annotations?, // override tool annotations
});Gating on what the target is, not on the tool name
For a screen-control tool, click(element_id) is harmless or a payment depending on the element. Give the tool a resolve function that looks the element up, and a gate for the labels you never want unattended:
registerConfirmedTool(server, {
name: "click", inputSchema: { element_id: z.string() }, /* preview, execute ... */
resolve: ({ element_id }) => screen.describe(element_id), // { label: "Buy now", role: "button", url }
gate: { pattern: /\b(buy|pay|delete|send|grant|allow)\b/i, fields: ["label"] },
autoApprove: (_args, _plan, ctx) => ctx?.role === "button", // only reached if the gate did not match
});The screen can change between approval and execution (a dialog opens, a list re-sorts), so resolve runs a second time right before execute. If the resolved context is different from the one the human approved, nothing runs, the audit log gets a context-changed event, and the model is told to ask again. A failed second lookup also refuses. In the token flow the token is bound to the resolved target as well. By default every returned field is compared; set pinFields: ["label", "role", "url"] to leave out volatile ones like coordinates.
Rules, all fail closed: a gate match always asks a human, even if autoApprove says yes. If resolve throws, rejects or returns anything other than a plain object (for example undefined for an unknown element), the call is never auto-approved. The approval prompt shows the resolved target (target label: Buy now) so the person sees what they are approving. Labels can be misleading (a button called "Continue" can submit a payment), so treat the gate as a first filter and also resolve the destination (url) for irreversible actions.
confirm_token is a reserved input name. More in docs/USAGE.md, including how to test your own tools with an in-memory client.
GitHub Actions in this repo
flowchart LR
A[Push or pull request] --> B[CI]
B --> B1[Build and 101 tests on Node 18, 20, 22]
B --> B2[Demo runs end to end]
B --> B3[Coverage report]
B --> B4[Mutation check: 42 deliberate bugs]
B --> B5[SVG diagrams valid]
C[Tag v*] --> D[Release]
D --> D1[Tests]
D1 --> D2[GitHub Release with notes]
D2 --> D3[npm publish with provenance, only if enabled]Workflow | Runs when | Does |
| every push to | Build, tests on Node 18/20/22, demo, |
| you push a tag like | Tests, GitHub Release, and npm publish if you enabled it |
| monthly | Opens update PRs for npm packages and Actions |
Add the same safety net to your own server's repo:
# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 22, cache: npm }
- run: npm ci
- run: npm test # include a test that the dangerous tool does NOT run without approvaltest/helpers.ts in this repo shows how to simulate a human who approves, declines, or never answers.
Roadmap
Elicitation flow, token fallback, timeouts, audit log, annotations
101 tests, 100% line coverage, mutation check, real stdio tests
Publish to npm
Approval channel for headless servers:
mode: "channel"+webhookApprover(point it at a service that can reach Slack or a dashboard)Policy:
autoApprovelets low-risk calls run, everything else still asks a humanContext-aware gating:
resolvelooks up what a call targets (e.g. the label behindclick(element_id)) andgateforces a human decision for labels like buy / delete / sendRe-check before execute:
resolveruns again right beforeexecuteand the call is refused if the target changed after approvalPython version for FastMCP servers
Contributing
Issues and PRs welcome: CONTRIBUTING.md. Any change to approval logic needs a test showing the action does not run without approval, and npm run mutation must still pass.
Star history
Support this project
If this helped you ship a safer agent, please star the repo, share it, or buy me a coffee:
License
MIT. See LICENSE. Copyright (c) 2026 Saurabh Pathak.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Preflight, approve, and prove consequential agent actions with signed evidence and x402 tools.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Hosted remote MCP for protected account access, permissions, activity history and supported undo.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA local-first stdio proxy for MCP servers that traps destructive tool calls and holds them for manual commit or discard, preventing accidental mutations.AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceMCP server that enforces single-use human confirmations for sensitive tool calls, sanitizes prompts against prompt injection, and re-validates file paths before destructive actions.62 PyPIMIT
- AlicenseNot gradedqualityBmaintenanceEnables Node 20+ developers to stand up single-file, zero-dependency MCP stdio servers whose destructive tools stay disabled by default, answering calls with a refusal and a dry-run preview until an environment variable turns them on. Also provides truthful empty/error results, secret redaction in logs, guarded stdout, and per-tool timeouts and cancellation.MIT
- AlicenseNot gradedqualityBmaintenanceEnables secure, cloud-agnostic MCP tool execution by authenticating agents, authorizing exact tools and arguments, enforcing independent one-time approvals, pinning upstream servers, and recording auditable decisions.27 npmMIT