Raposa Aval — human approval

raposa-mcp

Raposa Aval 是 DC ESCRYPT（https://raposa.group）提供的人工审批 MCP 服务。 它为 Agent 提供一项可靠的能力：在执行高风险操作之前，必须由一名具名人员明确批准。API 由欧盟基础设施提供；审批记录会封存在哈希链式审计日志中，可供审计人员导出。

https://dcescrypt.com · 文档 · 获取沙盒密钥

1 · 为什么审批必须默认拒绝

request_human_approval(action, context, risk) 返回：

{approved: true|false, decided_by, decided_at, comment, status, …}

只有在授权人员按下 Approve 后，approved 才为 true。所有其他结果—— 拒绝、过期、超时——都会返回 approved: false。沉默绝不代表同意：

结果	approved	含义
approved	true	一名具名人员在截止时间前批准
rejected	false	一名具名人员拒绝——不得继续
expired	false	TTL 已过且没有决定——不得继续；不会再收到该 id 的决定
timeout	false	在 wait_sec 内无人响应——请求会保持开放，直到 TTL 到期；稍后使用 get_approval 检查

Agent 必须根据 approved 进行分支处理；工具结果绝不会泄露密钥或机密。 已作出决定的审批不可更改：对同一 id 作出第二次决定会被拒绝，并返回 HTTP 409。 每项决定都会写入哈希链式审计日志（/v1/audit/verify、/v1/audit/export）。

2 · 架构

Agent ──tool call──▶ MCP server (raposa-mcp) ──HTTPS, Bearer RAPOSA_API_KEY──▶ Raposa Aval API
                                                                             │
                                                          approval created (status: pending)
                                                                             │
                     human sees it: e-mail link · web console · Slack · Telegram
                                                                             │
     agent ◀── polls get_approval / webhook callback ◀── decision (approve|reject)

• MCP 服务仅持有客户端 API 密钥。它会从环境中读取 RAPOSA_API_KEY， 且绝不会将其包含在工具输入或输出中。
• 审批按 API 密钥划分范围：一个客户绝不能读取或决定其他客户的 请求——外部 id 会返回 404 Approval not found，且只有操作员密钥才能作出决定。
• 决定会附带审批人身份和评论；拒绝重复作出决定。

3 · 获取 API 密钥

1. 注册免费沙盒：https://raposa.group/start/（每月 100 次审批）。
2. 你会收到一封标题为 “Raposa — your sandbox key” 的电子邮件，其中包含一个一次性领取 链接，有效期为 24 小时。该链接只显示一次密钥，且无法重复使用；链接过期或已使用时会返回 410 gone。
3. 领取链接本身就是凭证：任何人在 24 小时内首次打开该链接，就会成为密钥持有人。请将这封邮件视为机密——不要转发，也不要将链接粘贴到工单 或聊天中。如果你打开链接前它可能已泄露，请发送邮件至 [email protected]：未领取的链接会在 24 小时后自动过期，已领取的密钥则可在账户页面或通过支持团队撤销并重新签发。
4. 将密钥放入 MCP 服务的环境变量中（见下文）。

沙盒无需提供生产数据；结账后，付费方案密钥也会通过相同流程自动签发。

4 · 安装（安全分步指南）

该服务是一个 stdio MCP 服务，只需运行一条命令：uvx raposa-mcp（固定为 raposa-mcp==0.1.2 可锁定已发布版本）。

4.1 密钥绝不通过命令行传递

不要将 RAPOSA_API_KEY=<value> 写入聊天内容、shell 命令、屏幕截图或代码仓库。 有两种受支持的方式可将机密传递给 MCP 进程：

通过密钥管理器导出（1Password CLI，其他类似工具的用法也相同）：

# ~/.zshrc or ~/.bash_profile — resolved at login from your own vault
export RAPOSA_API_KEY="$(op read 'op://Dev-API/<your-item>/key')"

变量展开会在启动 MCP 客户端的 shell 内进行；密钥不会作为明文参数出现（否则它会显示在 ps、shell 历史记录和崩溃日志中）。

**纯环境变量替代方案：**将值保存在权限受限的文件中，并从 shell 配置文件中使用 source 加载。无论来源如何，始终遵守这条原则：MCP 进程必须从父环境继承该变量，而不能将其作为参数接收。

4.2 Claude Code

Claude Code 支持在 MCP 配置中使用 ${VAR} 展开——占位符会保存在配置文件中，并在服务启动时从环境变量解析（MCP 文档）：

claude mcp add raposa -e RAPOSA_API_KEY='${RAPOSA_API_KEY}' -- uvx raposa-mcp
claude mcp get raposa    # shows the ${...} reference — never the secret itself

单引号很重要：如果不使用单引号，Claude Code 保存占位符之前，Shell 就会先将其解析。运行 claude mcp get raposa，即可检查配置中是否未保存任何密钥。

4.3 通用 MCP stdio 配置（.mcp.json、其他客户端）

{
  "mcpServers": {
    "raposa": {
      "command": "uvx",
      "args": ["raposa-mcp"],
      "env": { "RAPOSA_API_KEY": "${RAPOSA_API_KEY}" }
    }
  }
}

4.4 检查配置，无需消耗密钥

# 1 · the stored placeholder is a reference, never the value:
claude mcp get raposa | grep -F '${RAPOSA_API_KEY}'     # prints the line — good
claude mcp get raposa | grep -F '<the key>'             # prints nothing — good
# 2 · end to end: list the tools (the server only runs when it can read the key):
#     three tools — create_approval, get_approval, request_human_approval
# 3 · a controlled read of a non-existent id must answer a 404 "Approval not
#     found", never a missing-environment error — that proves the key arrived

5 · 工具参考

这三个工具使用的参数完全相同（由客户端和服务端共同实施限制）：

create_approval

创建审批请求并立即返回其 ID（不会等待）。可配合 webhook_url 使用，或通过 get_approval 轮询。

参数	类型	必填	备注
action	string	是	≤ 200 个字符
context	string	是	≤ 4000 个字符
risk	string	是	low | medium | high
requested_by	string	否	≤ 200 个字符，默认值为 mcp-agent
expires_in_sec	integer	否	60–2592000（默认值 86400 = 24 h）
webhook_url	string (URL)	否	接收签名决策回调 POST 请求的地址

返回 {"id": "…", "status": "pending"}。

get_approval

参数	类型	必填
approval_id	string (UUID)	是

所有终态均返回相同结构：

{"id": "…", "status": "approved|rejected|expired|pending", "approved": true|false,
 "decided_by": "…", "decided_at": "…", "comment": "…", "message": "…"}

只有当 status == "approved" 时，approved 才为 true。

request_human_approval

参数与 create_approval 相同（不含 webhook_url），另加：

参数	类型	必填	备注
wait_sec	integer	否	轮询时长（每 5 s 轮询一次），默认值为 600

收到人工决策后，返回与 get_approval 相同的结构。达到截止时间后，返回 {"status": "timeout", "approved": false, "id": "…", "message": "Not approved — nobody answered in Ns. The request is still open; check later with get_approval."}——请求实际上 会一直保持待处理状态，直至 TTL 到期：你可以通过控制台或之后调用 get_approval 来处理逾期审批。

6 · 示例

实际输出（沙盒环境，uvx raposa-mcp==0.1.2）：

create_approval → 立即返回：

{"id": "79d647c1-…", "status": "pending"}

审批仍在等待时调用 get_approval：

{"id": "79d647c1-…", "status": "pending", "approved": false,
 "decided_by": null, "comment": null, "message": "Still waiting for a human."}

人工已批准（通过电子邮件链接或控制台）：

{"id": "79d647c1-…", "status": "approved", "approved": true,
 "decided_by": "<approver>", "decided_at": "2026-10-20T…", "comment": "owner mcp e2e approve",
 "message": "Approved by a human — proceed."}

人工已拒绝：

{"status": "rejected", "approved": false, "message": "Rejected by a human — do not proceed."}

TTL 已到期，仍无人决策：

{"status": "expired", "approved": false,
 "message": "Not approved — the request expired before anyone decided."}

调用 request_human_approval 并设置 wait_sec=8，仍无人响应：

{"id": "ed2e963e-…", "status": "timeout", "approved": false, "decided_by": null,
 "message": "Not approved — nobody answered in 8s. The request is still open; check later with get_approval."}

你实际会看到的错误结构：

针对外部或未知 ID 调用 get_approval——绝不会向外部密钥确认该 ID 是否存在：

Raposa API 404 on GET /v1/approvals/<id>: {"detail":"Approval not found"}

已决策的审批不会被更改：API 会拒绝第二次决策：

Raposa API 409 on POST /v1/approvals/<id>/decision

7 · 各角色的权限

角色	权限	范围
客户端（MCP 密钥）	为自己的审批创建请求、读取、轮询和接收 Webhook	仅限自己的审批；外部 ID 返回 404
操作员（人工决策路径）	决策、列出、验证审计链、导出审计记录	根据密钥配置，范围限定为单个客户或整个组织
所有者	内部方案：每月审批次数不限，可管理自己账户的密钥	配额不限，权限并非不受限制：仍适用相同的速率限制、隔离和审计要求

这里的任何内容都不会让 MCP 客户端密钥成为管理凭证。管理界面（操作员控制台）是独立的凭证访问区域，无法通过 MCP 密钥访问。

8 · MCP Rush 托管列表

同一服务也发布在 MCP Rush 托管基础设施上： darius-ceponas/raposa-aval-human-approval-mcp — 版本 0.1.1，包含三个工具，已扫描并验证（信任评分 96/100，等级 A）。 网关已上线，且会拒绝未携带买家令牌的调用。

如实说明： 托管版本可以响应，但尚未使用真实买家凭据验证端到端网关调用——撰写本文时，市场的 Access 页面（买家在此生成所需网关密钥）无法访问，发布者已向 MCP Rush 支持团队报告此问题。在问题解决之前，§ 4 中的直接 uvx 安装方式是受支持的方案；本 README 不声称端到端网关调用已验证。

9 · 故障排除

症状	原因	修复方法
RAPOSA_API_KEY is not set. Get a free sandbox key at …	变量未传递到 MCP 进程	在启动客户端的 shell 中导出变量；检查 claude mcp add 是否使用了 ${VAR} 占位符，而不是空值
直接调用 API 时出现 HTTP 401 Invalid API key	密钥已撤销或输入错误	从密码库中重新读取该值；从账户页面轮换密钥
使用正确 ID 时出现 404 Approval not found	审批属于另一个密钥，或 ID 输入错误	审批按租户隔离；请使用创建该审批的密钥
429 … Rate limit exceeded (60/min for your plan)	每个密钥的每分钟速率限制（防滥用措施，所有套餐均启用）	遵循 Retry-After；批量处理 Agent 工作
第二次决策时出现 409	审批已进入终态	终态决策不可更改
无人应答时出现 timeout	wait_sec 在每隔 5 秒轮询后到期	请求会保持打开状态，直到 TTL 到期；联系人工后调用 get_approval
客户端首次调用时挂起约 1 分钟	托管服务／网关服务冷启动，或软件包缓存	重试；第二次调用会很快
声明链接提示 410 gone	一次性链接已打开或已过期（24 h）	密钥已显示过一次；重新注册以获取新链接

10 · 开发

本仓库即 MCP 软件包本身：

pip install -e ".[test]" && pytest -q

11 项契约测试使用模拟传输运行：工具会连同其架构一起列出；批准／拒绝／超时／过期状态均会以默认拒绝的方式回读；创建操作会返回 ID，而不会等待；API 错误会被报告，而非吞掉；未知风险不会传递给 API；缺少密钥时会明确报错，但工具列表仍可正常使用。

后端 API（配额、密钥轮换、一次性声明链接、租户隔离、面板作用域、速率限制、webhook、Stripe、Slack/Telegram 频道、审计链）位于单独的仓库，并有其自身的测试套件；这些 pytest 运行不会测试该后端 API。

• 源代码和问题反馈：https://github.com/agentlabbusiness/raposa-mcp
• 文档：https://raposa.group/docs/
• 法律信息：MIT License — © DC ESCRYPT SL（参见 LICENSE）
• 联系方式：[email protected]

Raposa Aval 是 DC ESCRYPT 的产品。