Quirna

@quirna/mcp

在 Agent 执行操作前征得人工同意。适用于 Model Context Protocol 的官方 Quirna 服务。

添加一段配置，Agent 就会获得一个工具，可在执行重要操作前调用它，例如退款、生产环境部署或破坏性迁移。指定的人员会在手机上批准。只有在对方同意后，Agent 才会继续操作，并且决策会签名留存。

未经同意，任何操作都不会执行。

你的 Agent 框架可能已经支持暂停并等待确认。但在不再只是你独自操作终端时，两者有三点重要区别：

• 决策会跳出执行流程。 决策会发送给策略指定的人员，在他们的手机上通过 Face ID 验证，而不是发给碰巧正在看着 Agent 运行的人。
• 审批人由策略指定，而非提示词指定。 配额、风险等级和接收请求的群组都在组织的设置中配置。Agent 无法自行选择审批人，提示注入也不能。
• 决策会留下证据。 每项决策都会在做出时签名，并导出到文件，第三方无需信任我们也能验证。

安装

无需安装：下方的配置会使用 npx 按需运行。要固定版本，请运行 npm install -g @quirna/mcp，并将 quirna-mcp 用作命令。

开始之前

移动应用目前处于私人测试阶段。 决策只能在手机上做出，不能在其他地方做出；Console 用于配置策略，但不会做出决策。因此，没有该应用时，审批请求会被创建，然后一直等待，直到过期。请写信至 [email protected]，我们会为你开通权限。以下其他内容目前均可使用。

然后，在 Console 中：

1. 系统密钥。 打开 Users → Systems，为此 Agent 注册一个系统。你会获得一个密钥（ck_…），且只会显示一次。
2. 策略，用于决定谁来审批某类请求，以及需要多少人审批。
3. 应用，安装在负责审批人员的手机上。

配置 Agent

Claude Code — claude mcp add quirna --env QUIRNA_API_KEY=ck_… -- npx -y @quirna/mcp

Cursor（~/.cursor/mcp.json）、Claude Desktop （claude_desktop_config.json）以及大多数其他客户端使用相同的配置格式：

{
  "mcpServers": {
    "quirna": {
      "command": "npx",
      "args": ["-y", "@quirna/mcp"],
      "env": {
        "QUIRNA_API_KEY": "ck_your_system_key",
        "QUIRNA_REQUESTER_NAME": "Ops Agent",
        "QUIRNA_ENVIRONMENT": "production"
      }
    }
  }
}

环境变量

变量	默认值	作用
QUIRNA_API_KEY	—	必填。 来自 Console 的系统密钥。
QUIRNA_REQUESTER_NAME	AI agent	审批人看到的请求发起者名称。
QUIRNA_REQUESTER_ID	mcp	此调用方在审计记录中的稳定 ID。
QUIRNA_ENVIRONMENT	—	调用未指定环境时使用的环境。
QUIRNA_WAIT_MS	90000	工具调用等待并返回结果前的时长。
QUIRNA_BASE_URL	https://api.quirna.com	指向可自托管的 API。

关于密钥。 密钥保存在 Agent 客户端的配置文件中，该文件通常是点文件，有时也会位于代码仓库中。请将其视为部署凭证：为每个 Agent 单独创建一个系统，而不要共用；在 Console 中限制其可请求的类型；如果密钥文件出现在不该出现的地方，请在 Console 中轮换密钥。系统密钥只能发起请求，绝不能批准任何事项。

工具

request_approval

创建请求并等待人工审批。

参数	必填
kind	是	操作类别，例如 database_migration。用于选择策略。
message	是	一行祈使句，将作为标题显示在手机上。
identifiers	否	审批人需要的扁平字符串键值对：金额、表名、主机名。
environment	否	production、staging 等。
tier	否	routine、elevated、critical。只能提高策略设定的最低等级。

特别没有列出的是：由谁审批、需要多少人审批、请求会保持开放多长时间。这些由组织在 Console 中统一决定，并适用于所有调用方——如果 Agent 能自行选择审批人，这就不算一种管控。

check_approval

接收一个 approval_id，并等待对应的现有请求。当 request_approval 返回时请求仍处于待处理状态，就使用它；再次调用 request_approval 会把同一操作提交给第二个人审批。

Agent 会收到什么结果

凡是结果不是 APPROVED，开头都会显示 NOT AUTHORIZED，随后说明原因，并明确指示不要执行该操作。结构化结果中包含 authorized: true | false，供解析结果而非阅读结果的代码使用。

无论得到什么答复，提出请求并获得答复都算工具调用成功——拒绝正说明产品正常运作，并非失败。只有工具完全无法运行且没有获取到任何信息时，才会使用 isError：Quirna 无法访问、密钥被拒绝或调用中止。因此，Agent 可以区分“人工拒绝了请求”和“审批系统不可用”这两种截然相反的情况，也不会引导它将遭拒的请求重试并交给第二个人审批。

无人答复时

凌晨 3 点无人值守运行的 Agent 会遇到这种情况：请求过期，操作始终未获授权。这是正确结果，不是需要设法绕过的错误。如果你的 Agent 需要在无人值守时运行，正确做法是为相应情况制定无需人工审批的策略，而不是延长超时时间。

这里涉及两个超时，它们并不相同：

• QUIRNA_WAIT_MS（默认值为 90s）是 工具调用 等待的时长，超时后会返回审批 ID，供 Agent 恢复处理。它的存在是因为 Agent 客户端会终止耗时过长的工具调用。请求仍会保持有效。
• 策略的有效期（在 Console 中设置）是 请求 保持待处理状态的时长。只有这个超时会使请求过期。

链接

• quirna.com — 了解它是什么
• console.quirna.com — 策略、群组和系统
• @quirna/sdk — 用于在你自己的代码中调用 Quirna

MIT © Quirna