mcpcut

mcpcut

查看 AI Agent 通过 MCP 发出的每次工具调用，将有风险的调用暂缓以供你审批，只向它开放所需文件夹，并保留一份经过密钥脱敏、且通过外部锚定防篡改的日志。

可自托管 · Apache-2.0 · Node.js 24+ · 仅有两个运行时依赖。从笔记本电脑上的单个服务开始；再扩展为服务多个 Agent 的控制平面。

快速开始

需要 Node.js 24+（node -v）；在较旧版本的 Node 上，mcpcut 会输出一行提示并退出——使用 nvm、fnm 或 volta 安装 Node 24。无需安装其他内容。

查看。 将已有的 MCP 服务接入 mcpcut。adopt 会在 Claude Code、Cursor 和 Claude Desktop 中查找这些服务（在项目文件夹中运行，即可包含其中的 .mcp.json），并展示变更；--apply 会写入变更，同时为每个文件保留副本（adopt --undo 可还原）。然后重启客户端：

npx -y [email protected] adopt
npx -y [email protected] adopt --apply

也可以手动将 mcpcut 放到单个服务前面——以下以 Claude Code 为例；在其他客户端中，将服务的命令改为 npx -y [email protected] wrap -- <your server>：

claude mcp add fs -- npx -y [email protected] wrap --server fs -- npx -y @modelcontextprotocol/server-filesystem ~/project

在 Windows 上，npm 命令只能通过 cmd /c 启动（adopt 会为你添加它）——手动配置时，将它放在两个 npx 前面：

claude mcp add fs -- cmd /c npx -y [email protected] wrap --server fs -- cmd /c npx -y @modelcontextprotocol/server-filesystem C:\path\to\project

首次启动时会下载 mcpcut 和服务；如果客户端放弃等待，请再启动一次。让 Agent 开始工作，然后运行 npx -y [email protected] sessions 和 npx -y [email protected] show <id>：查看每个请求和响应，密钥均已脱敏（启用策略后，也会记录每项决策）。--server fs 用于指定服务名称；策略写入日志的决策和审批队列都会使用此名称。

拦截。 将以下内容保存为 ~/.mcpcut/data/policy.json——mcpcut 后面的每个服务都会在启动时读取该文件——然后重启客户端。读取操作会通过，其他所有操作都需要等待你审批（新工具隔离功能默认关闭，因此最初只会看到一道关卡：参见隔离）：

{ "version": 1, "defaultDecision": "require-approval", "classDefaults": { "read": "allow" },
  "quarantine": { "enabled": false } }

手动添加的服务也可以使用自己的策略文件：在 wrap 后紧跟 --policy "$PWD/policy.json"。

现在，写入操作会一直等待，直到 Agent 不再等待（Claude Code 会在两分钟后将其移至后台，之后再获取结果）。在另一个终端中批准——添加首位管理员之前无需令牌。批准操作只会发送该调用；如果 Agent 不再等待，请求就会关闭，不会发送任何内容（审批）：

npx -y [email protected] approvals list
npx -y [email protected] approvals approve <id>

或者，直接在会话中接受询问：允许所有操作通过，只拦截你指定的工具——Claude Code 会显示 Accept / Decline，无需使用第二个终端。fs 是客户端中的服务名称——adopt 会保留这些名称（在客户端中确认）： { "version": 1, "defaultDecision": "allow", "quarantine": { "enabled": false }, "servers": { "fs": { "confirmInClient": { "write_file": [""], "edit_file": [""] } } } }

与其编写 JSON，不如点击操作？运行 npx -y [email protected] ui 即可打开管理 UI。在 Servers 页面，点击 Create policy 会创建一条允许所有调用通过的策略——重启一次客户端——之后，mcpcut 后的每个服务中的每个工具，其按钮都会出现在服务卡片的 view → 下（服务首次被调用后才会显示在这里）：client 下的 all 会让该工具在会话中向你确认，approval 会将其加入队列等待审批，deny 则会阻止它。每次点击都会在下次调用时生效。

验证。 为历史记录签名并导出，然后离线检查——只需目录和 keygen 打印出的公钥（在另一台机器上，使用 --pub 传入）：

npx -y [email protected] keygen && npx -y [email protected] export --report --out ./report
npx -y [email protected] verify --report ./report
npx -y [email protected] verify --sign

最后一行会为链头签名：请将其打印内容保存在这台主机无法改写的地方——带外锚点才是让日志具备防篡改能力的关键，光有哈希并不足够。

扩展。 运行 npm install -g mcpcut，然后运行 mcpcut：先完成设置向导，再配置服务注册表、每个 Agent 的密钥和授权、凭据保险库、Web UI、终端控制台，以及每个 Agent 的独立地址（安装和首次运行）。

你将获得

• 日志 — 记录每个请求、响应和决策，并在写入任何内容之前对机密信息进行脱敏。也可选择故障时默认拒绝：没有记录，就不调用。

• 按工具设置策略 — 按服务、工具名称或工具类别设置 allow、deny 或 require-approval；只读工具可以自动通过。

• 审批 — 高风险调用会一直等待，直到 Agent 不再等待，或你通过 CLI、Web UI、终端控制台，或直接在 Claude Code 会话中批准该调用。如果 Agent 停止等待，就不会发送任何内容；Claude Code 重试已批准的调用时会收到第一次的响应，不会重复执行。

• 隔离 — 新工具，或你信任后描述或架构发生变化的工具，都会被暂扣，直到审核完成，并附上变更差异。

• Agent 和授权 — 服务注册表、每个 Agent 各自的密钥、按工具授权、分组以及加密保险库，因此服务凭据不会存放在 Agent 的配置中。

• Agent 文件夹 — 内置文件工具可操作你指定文件夹中的文件。可按 Agent 或分组设置权限，并沿目录树继承；最具体的规则优先，空规则则会将某个子文件夹排除在外。删除的文件会移至可恢复的回收站，每次调用都会记录在审计日志中（files audit，以及管理 UI 的 Files 页面）。还可选用本地 Postgres 实现完整审计，并在本机进行语义搜索。

  mcpcut files root add ~/project
  mcpcut files grant research-bot ~/project --ops read,write,edit
  

• 每个 Agent 一个地址 — 将授权给 Agent 的每个服务都放在一个端点后；无需改动客户端即可授予或撤销授权。

• 证据 — 哈希链及其签名链头，以及任何人都能使用公钥离线验证的审计报告。

• 管理 UI和终端控制台 — 设置命名管理员，并分配 owner、operator 和 viewer 角色；每项变更都会在日志中注明操作者。

工作原理

 AI agent ── stdio or HTTP ──▶ mcpcut ──────────────────▶ MCP servers
 (Claude Code,                 grants → policy →          (filesystem,
  Cursor, …)                   quarantine → approval       GitHub, …)
                                 │
                                 ▼
                     journal.db — redacted, hash-chained
                                 │  export --report
                                 ▼
                     verify offline, anywhere

三种接入方式，一个入口：

• wrap — 在单个服务前接入，无需设置，也无需身份验证：参见上方的快速入门。
• connect 和 serve — 从注册表选择命名服务，每个 Agent 使用一个密钥，凭据从保险库获取。
• 服务池（/mcp） — 每个 Agent 使用一个地址访问获准使用的所有服务；connect --url 可将另一台机器上的 stdio 客户端桥接到该地址。

完整说明（含信任边界）：docs/ARCHITECTURE.md。

文档

指南	涵盖内容
安装和首次运行	npm 或源码安装、设置向导、首位所有者、通过 IP 访问服务
封装服务并查看日志	wrap、sessions、show、.mcp.json、失败时默认拒绝的日志记录、已知限制
策略、审批和隔离	policy.json、工具类别、审批、隔离、tools/list 过滤
注册表、Agent 和保险库	服务、Agent 密钥和授权、组、撤销访问权限、保险库
为 Agent 提供文件夹	内置文件服务：根目录、每个 Agent 的权限、回收站、审计、可选的 Postgres 和语义搜索
HTTP Agent 和服务池	serve、每个 Agent 使用一个地址、connect --url
管理 UI	Web 控制台、管理员和角色、威胁模型
终端控制台	在终端中使用 mcpcut、远程控制台
服务、Docker 和备份	start/stop/status、systemd 和 launchd、Docker、备份和恢复
审计报告和保留策略	export --report、verify --report、带外锚点、prune
CLI 参考	所有命令和标志
状态	已发布的功能，以及每项功能的证据

状态

mcpcut 目前为 0.x 版本。核心功能——代理、策略、审批、隔离、日志、审计报告、内置文件服务、管理 UI 和控制台——均已发布并经过测试；状态列出了每项功能及其证据。

• **预览版：**远程控制台（mcpcut --remote）和用于连接另一台机器上服务的 connect --url 桥接功能。它们可正常工作，并已通过 TLS 在 VPS 上完成测试，但会在网络上传输令牌，目前仅经过内部安全审查，且可能在 0.x 版本期间发生变化。在同一台机器上，桥接到本地 serve 的方式——agent create 打印的客户端配置——是常规接入方式，不属于预览版。
• **具备防篡改能力，但需要外部锚点。**以同一 OS 用户身份运行的进程可以重写日志并重新签名；只有将链头记录在此主机无法写入的位置，才能发现这种篡改。mcpcut 并非不可篡改，报告是否符合审计要求由审计员判定。
• **用于防止误操作的刹车，不是沙箱。**同时拥有你这个用户身份的 shell 的 Agent，也能访问你运行的同一个 approvals approve 命令：管理员令牌会记录审批者身份，但无法阻止同一 OS 用户执行操作（审批）。被拦截调用返回的错误会告知 Agent 必须由人工审批，但绝不会透露命令名称。

安全

请私下报告漏洞——具体方式请参阅 SECURITY.md。整个产品于 2026 年 9 月接受了内部安全审计；目前尚未进行独立审计。

贡献

欢迎提交 Issue 和拉取请求——请参阅 CONTRIBUTING.md。

许可证

Apache-2.0——另请参阅 NOTICE。