MCP Safe Actions

io.github.techsaurabh-394Published by GitHub account techsaurabh-394v1.5.0Updated Nov 16, 2026

File server whose delete tool asks a human first (elicitation or one-time token), with audit log.

The publisher's own server: actions.world

VerifiedSTDIODesktop only

Overview

MCP Safe Actions's local MCP server; no sign-in required; STDIO; 2 tools.

No AI overview yet: these facts come from the registry entry and the server itself.

Installation

In SourceWeft

  1. Open MCP Safe Actions in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[mcp-safe-actions: human approval for destructive MCP tools]

[CI] [101 tests passing] [100% line coverage] [TypeScript strict] [MIT]

[Image] Star this repo if it saves you from a bad tool call  ·  [Buy me a coffee]

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.

[Animated terminal: the human declines and nothing is deleted; then the token fallback issues a single-use token that cannot be reused]

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.

Try it as a ready-made MCP server

It also ships a small file server where deleting needs a human OK. Add it to your MCP client config:

json
{ "mcpServers": { "safe-files": { "command": "npx", "args": ["-y", "mcp-safe-actions"], "env": { "FILES_DIR": "/path/to/folder" } } } }

Tools: list_files and delete_file (asks you first). Set AUDIT_LOG to keep a JSONL log. Listed in the official MCP Registry as io.github.techsaurabh-394/mcp-safe-actions.

Add it to your MCP server in 4 steps

1. Install

bash
npm install mcp-safe-actions

Published 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):

ts
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

bash
git clone https://github.com/techsaurabh-394/mcp-safe-actions.gitcd mcp-safe-actionsnpm installnpm run demo      # prints both approval flowsnpm test          # 101 tests

4. Connect it to an MCP client

Claude Desktop (claude_desktop_config.json), using the included example server and a throwaway folder:

json
{  "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

[Flow: model calls, server previews, human approves, action executes, audit logged]

Client supports elicitation (best case):

mermaid
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.    end

Client without elicitation (token fallback):

mermaid
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.pdf

Decision table

SituationResult
Elicitation accepted and the box is tickedexecute() runs
Declined, cancelled, unticked, timed out or erroredNothing runs
mode: "elicit" and the client has no promptsRefused, no token issued
Token flow, no tokenPreview plus one-time token, nothing runs
Token flow, valid token and identical argumentsexecute() runs once
Reused, expired, unknown, or for other arguments or another toolNothing runs, reason returned

Modes

modeBehaviourUse when
"auto" (default)Elicitation if supported, otherwise tokenMost servers
"elicit"Elicitation onlyActions that must have a human gate
"token"Always the token flowTesting, or by preference
"channel"Asks your approver (e.g. webhookApprover(url))Headless servers with no client UI

Proof it works: tests that try to break it

101 testsUnit, 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 (src/), 96.8% to 100% of branchesnpm run coverage
42 deliberate bugs, all caughtnpm run mutation breaks the code on purpose (token reusable, approval skipped on error, secrets in the log, ...) and fails if the tests don't notice

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 guaranteesHow
Nothing runs before approvalexecute() is reachable only after an accepted prompt or a valid token
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 expireChecked server-side
Failures fail closedErrors and timeouts never fall through to execution
Audit without leaking secretsLogs 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

ts
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:

ts
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

mermaid
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]
WorkflowRuns whenDoes
ci.ymlevery push to main and every pull requestBuild, tests on Node 18/20/22, demo, npm pack check, coverage, mutation check, SVG validation
release.ymlyou push a tag like v1.2.0Tests, GitHub Release, and npm publish if you enabled it
dependabot.ymlmonthlyOpens update PRs for npm packages and Actions

Add the same safety net to your own server's repo:

yaml
# .github/workflows/ci.ymlname: CIon: [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 approval

test/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: autoApprove lets low-risk calls run, everything else still asks a human
  • Context-aware gating: resolve looks up what a call targets (e.g. the label behind click(element_id)) and gate forces a human decision for labels like buy / delete / send
  • Re-check before execute: resolve runs again right before execute and the call is refused if the target changed after approval
  • Python 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

[Star History Chart]

Support this project

If this helped you ship a safer agent, please [Image] star the repo, share it, or buy me a coffee:

[Buy me a coffee]

License

MIT. See LICENSE. Copyright (c) 2026 Saurabh Pathak.


Saurabh Pathak · AI Engineer & Full-Stack Developer
GitHub · LinkedIn · Blog · [email protected]

Source: README.md at commit 4add76f

Tools

2

list_files

List files in the allowed folder.

Takes no parameters.

delete_file

Permanently delete one file from the allowed folder. DESTRUCTIVE: the user must approve before anything happens. Describe the action to the user and wait for their answer.

Parameterspathrequiredconfirm_token

Version history

1
  1. v1.5.0LatestNov 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Actions integrations

actions.world

world.actionsOfficial publisher

Remote MCP server that lets an assistant run video actions on actions.world datasets and track the resulting runs.

Streamable HTTPWeb executableAuth
Media & DesignCredential requiredOct 30, 2026

Meeting decisions and actions extract — Atom

org.aimlds

Meeting decisions and actions extract — Atom's hosted MCP server, published by aimlds.org; credential required; Streamable HTTP.

Streamable HTTPWeb executableAuth
Credential requiredNov 16, 2026

Apple Mail Actions

Published by GitHub account redpop

A macOS-only companion server that lets an assistant move Apple Mail messages between mailboxes and optionally save a single attachment to a local folder.

STDIODesktop only
Files & StorageNot validated · the package did not installNov 15, 2026

NSE Corporate Announcements (Apify) - NSE India filings, corporate actions, bulk and block deals

Published by GitHub account datadmon

Apify-hosted MCP server that returns NSE India corporate filings as JSON: announcements, ex-dates, board meetings, bulk and block deals and ratings.

Streamable HTTPWeb executableAuth
Web Search & ScrapingCredential requiredNov 11, 2026

BSE Corporate Announcements (Apify) - BSE India filings, corporate actions, bulk and block deals

Published by GitHub account datadmon

Apify-hosted MCP endpoint that returns BSE India corporate filings — announcements, ex-dates, board meetings, results dates and deals — as JSON.

Streamable HTTPWeb executableAuth
Web Search & ScrapingCredential requiredNov 11, 2026