Approval gate for databases

数据库 MCP 服务的审批门

@hibira-io/mcp-approval-gate 位于连接助手与数据库的 MCP 服务前。读取操作直接通过。任何会更改数据或架构的操作，都必须等到另一人在托管审批页面上批准后才能执行；审批请求会以推送通知的形式发送到对方手机上。随后，该操作只会执行一次，并且与获批的内容完全一致。

_{真实会话：Claude Code 通过 DBHub 请求将订单 1042 标记为已退款。UPDATE 会等待审批，而助手不会收到审批链接。请求会显示在店铺经理手机上的 Hibira Approvals 收件箱中（也会以推送通知的形式发送给她）；她打开请求，检查语句并批准后，助手才完成更改。(MP4 · 同一请求被拒绝)}

它适用于任何 MCP 服务，并已通过以下服务的测试：

• DBHub（Postgres、MySQL、MariaDB、SQL Server、SQLite）
• Postgres MCP Pro（postgres-mcp）
• Supabase MCP（本地或 mcp.supabase.com）

并且适用于 Claude（Desktop、Code 和 claude.ai）、Cursor、ChatGPT 及其他任何 MCP 客户端。

assistant ──► approval gate ──► database MCP server ──► database
                  │  writes only
                  ▼
        Hibira approval page + push ──► supervisor taps Approve / Reject

为什么需要它

大多数数据库 MCP 服务只提供两种选择：只读，或允许助手进行任意写入。客户端侧“允许使用此工具？”的提示由提出请求的同一个人来回答。审批门增加了团队在生产数据操作中通常需要的步骤：由另一人担任主管进行审批，并在其面前显示确切的语句。

• 绑定到确切的调用。 审批针对一个工具调用及一组参数（并显示其指纹）。如果语句发生变化，就需要重新审批。获批的调用只会执行一次。
• 默认拒绝。 审批门无法解析的 SQL，以及无法确认是只读的工具，都必须等待审批。如果无法连接审批服务，就不会执行任何操作。
• 数据库仍由你掌控。 审批门运行在数据库 MCP 服务所在的位置。Hibira 只会看到审批请求（标题、语句、工具名称），绝不会看到你的连接字符串或查询结果。
• 审核者一目了然。 页面会显示数据库标签、更改类型（UPDATE、DROP TABLE 等）、诸如“没有 WHERE 条件的 DELETE 会更改所有行”之类的警告，以及完整语句。

## 设置

1. 在 approvals.hibira.io 创建 Hibira Approvals 工作区， 并邀请审批人员（门店经理、DBA 等）。他们会在手机上收到请求，并在审批收件箱中作出决定。
2. 在客户端配置中（见下文），将审批门禁放在数据库 MCP 服务前面。 -- 后面的内容都是数据库服务的常规命令。 无需复制任何密钥。
3. 助手第一次尝试修改内容时，会返回一个链接和一段简短代码。工作区管理员打开链接，选择工作区，然后点击 Connect。之后，审批门禁就会保持连接；读取操作始终可用。

如果想提前在终端中连接，请运行 npx -y @hibira-io/mcp-approval-gate login。status 和 logout 的用法也相同。连接凭据是一个令牌，保存在 ~/.config/hibira/approval-gate.json 中，该令牌只能请求并读取该工作区的审批。管理员可以在工作区设置中查看所有已连接的审批门禁，并随时撤销其中任意一个。

Claude Code

claude mcp add shop-db -e GATE_LABEL=shop-production \
  -- npx -y @hibira-io/mcp-approval-gate \
  -- npx -y @bytebase/dbhub --transport stdio --dsn "postgres://user:pass@host:5432/shop"

Claude Desktop、Cursor、Windsurf、VS Code

claude_desktop_config.json、.cursor/mcp.json 等配置文件格式相同：

{
  "mcpServers": {
    "shop-db": {
      "command": "npx",
      "args": [
        "-y", "@hibira-io/mcp-approval-gate",
        "--label", "shop-production",
        "--",
        "npx", "-y", "@bytebase/dbhub", "--transport", "stdio",
        "--dsn", "postgres://user:pass@host:5432/shop"
      ]
    }
  }
}

postgres-mcp：

"args": ["-y", "@hibira-io/mcp-approval-gate", "--label", "analytics", "--",
         "uvx", "postgres-mcp", "--access-mode=unrestricted"],
"env": { "DATABASE_URI": "postgresql://..." }

这里使用 --access-mode=unrestricted 没问题：审批门禁会拦住写入操作。

Supabase（本地服务）：

"args": ["-y", "@hibira-io/mcp-approval-gate", "--label", "supabase-prod", "--",
         "npx", "-y", "@supabase/mcp-server-supabase@latest", "--project-ref=<project-ref>"],
"env": { "SUPABASE_ACCESS_TOKEN": "sbp_..." }

带有 SELECT 的 execute_sql 会立即执行；写入操作、apply_migration、 deploy_edge_function、分支合并和项目暂停则需要等待审批。

Supabase（托管服务）：

"args": ["-y", "@hibira-io/mcp-approval-gate", "--label", "supabase-prod",
         "--upstream-url", "https://mcp.supabase.com/mcp?project_ref=<project-ref>",
         "--header", "Authorization: Bearer ${SUPABASE_ACCESS_TOKEN}"],

ChatGPT 和 claude.ai（远程）

Web 客户端需要 HTTPS URL，因此请在数据库旁运行审批门禁作为小型服务，并为其配置 HTTPS（使用反向代理、隧道，或 Fly.io、Railway 等平台）：

npx -y @hibira-io/mcp-approval-gate login      # once, on the server
export GATE_TOKEN="$(openssl rand -hex 24)"   # keep it secret
npx -y @hibira-io/mcp-approval-gate --http --host 0.0.0.0 --port 8787 \
  --label shop-production \
  -- npx -y @bytebase/dbhub --transport stdio --dsn "$DATABASE_URL"

端点为 https://your-host/mcp/<GATE_TOKEN>；支持发送请求头的客户端也可以使用 https://your-host/mcp，并设置 Authorization: Bearer <GATE_TOKEN>。

• **ChatGPT：**Settings → Apps & Connectors → Advanced → Developer mode，然后 选择 Create：粘贴带令牌的 URL，并将身份验证设为 "No authentication"。
• **claude.ai：**Settings → Connectors → Add custom connector，粘贴带令牌的 URL。

如果监听地址不是本地地址，且未设置 GATE_TOKEN，审批门禁会拒绝启动监听。 项目包含一个 Dockerfile。在容器中，由于无法通过终端登录，请将工作区令牌作为 HIBIRA_APPROVALS_TOKEN 传入（在任意机器上执行 login 后，从 ~/.config/hibira/approval-gate.json 复制令牌），或者在首次启动时查看审批门禁日志中的连接链接。

不止数据库：预设

审批门禁可用于任何 MCP 服务。针对一些常见服务，--preset 可以识别哪些工具只执行读取、哪些工具会进行修改，并为审批请求生成清晰的标题，例如“Stripe：POST /v1/refunds”或“GitHub：合并拉取请求 acme/shop#42”。对于预设，--allow 和 --gate 仍具有更高优先级。

预设	等待审批	立即执行
stripe	stripe_api_write、send_money、transfer_money、convert_currency、……	stripe_api_read、搜索、文档、分析
github	合并、推送、文件更改、新建仓库、工作流运行、评论	get_*、list_*、search_*、*_read
gmail	发送、回复、转发、删除、筛选条件	读取、搜索、草稿
shopify	graphql_mutation、创建、更新、折扣、库存	查询、分析、文档

Stripe（托管服务，使用 Agent API 密钥）：

claude mcp add stripe -- npx -y @hibira-io/mcp-approval-gate --preset stripe \
  --upstream-url https://mcp.stripe.com --header 'Authorization: Bearer ${STRIPE_AGENT_KEY}'

GitHub（Docker 中的官方服务）：

claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=... \
  -- npx -y @hibira-io/mcp-approval-gate --preset github \
  -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

对于 Gmail 和 Shopify，请在你当前使用的服务命令前添加 --preset gmail 或 --preset shopify。预设无法识别的工具将遵循下文的常规规则。

助手会看到什么

写入调用会通过 --wait 等待决策，最长 50 秒，并发送进度更新，避免客户端过早放弃：

• **已批准：**调用会执行并返回正常结果，同时附上一行说明该调用已获批准。
• **已拒绝或已过期：**返回错误，说明调用未执行；如果主管留下了评论，也会一并显示。
• **仍在等待：**返回简短答复，说明需要主管批准，并附带 approval_id。该审批门会添加一个工具 check_approval：当用户表示已有决定时，助手会用该 approval_id 调用此工具；如果调用已获批准，就会执行。再次请求相同的调用会复用同一请求。

当审批门连接到 Approvals 工作区时（其成员会收到通知并在登录后作出决定），或请求通过其他方式送达主管时（--push-interests、--push-users 或 --channel），助手不会获得审批链接，因此与助手聊天的人无法在聊天中批准自己的更改。如果没有使用上述任何方式，链接就是联系主管的唯一途径，因此助手会显示该链接，供你转发。--show-link always 或 never 可覆盖此设置。

哪些操作需要等待批准

使用默认的 --mode writes 时：

1. --gate 中列出的工具始终需要等待；--allow 中的工具则无需等待（末尾的 * 会匹配前缀）。
2. 含有 SQL 的调用（参数名为 sql、query、statement、queries 等）如果有任何语句会更改内容，就需要等待：INSERT、UPDATE、DELETE、MERGE、CREATE、ALTER、DROP、TRUNCATE、GRANT、COPY、CALL、DO、SET、VACUUM、会更改数据的 WITH、SELECT ... INTO、对写入操作执行的 EXPLAIN ANALYZE、调用 setval 或 pg_terminate_backend 等函数的 SELECT，以及任何无法解析的语句。注释、字符串和美元引用的代码块会被跳过，因此 SELECT 'DROP TABLE x' 属于读取操作。
3. 其他工具如果标记了 readOnlyHint，或名称类似读取操作（list_、get_、search_、describe_、explain_、analyze_ 等），则可直接通过。其他所有工具都需要等待。

--mode all 会让每次调用都等待批准，包括读取操作。--mode none 会关闭审批门（适合测试时使用）。

审批门只是额外的一双眼睛，并非权限系统。还要仅授予数据库用户所需的权限。

编码 Agent：高风险 Shell 命令需先审批

同一软件包也可作为 Claude Code、Codex、Cursor 和 Hermes Agent 的钩子。难以撤销的 Shell 命令会等待 Hibira 审批工作区中的另一人批准；其他命令照常执行。

等待审批	示例
删除文件	rm -rf src、find . -delete、git clean -fdx（不包括 rm -rf node_modules、dist、build 等）
重写 Git 历史	git push --force、git reset --hard、git branch -D、删除远程分支
部署和发布	vercel --prod、fly deploy、wrangler deploy、firebase deploy、gh pr merge、npm run deploy、make release
基础设施	terraform apply / destroy、pulumi up、cdk deploy、kubectl delete / apply、helm upgrade、aws ... delete-*
发布	npm publish、cargo publish、twine upload、docker push、gh release create
数据库	psql -c "DELETE ..."、SQL heredoc 和文件、prisma migrate deploy、artisan migrate --force、redis-cli FLUSHALL

命令会按照 Shell 的解析方式读取（&&、管道、$( )、heredoc）， 并会解析 sudo、env、bash -c、ssh host '...'、npx 和 uv run 等封装命令。SQL 的分类方式与 MCP gate 相同：psql -c "select ..." 会执行，DELETE 则会等待审批。使用 npx -y @hibira-io/mcp-approval-gate hook check -- terraform apply 检查任意命令。

审批请求会显示完整命令、等待审批的原因、文件夹、仓库和分支，以及计算机信息。审批者会在手机上收到请求；Agent 不会收到审批链接，因此无法自行批准。批准后，该命令可在该文件夹中执行一次。拒绝（附带评论）后，请求会连同停止执行的指示返回给 Agent；如果 10 分钟内无人响应，Agent 会收到等待指示，并在稍后重新运行同一命令。

命令会在你的计算机上检查：只有需要等待审批的命令才会创建请求（并计入工作区的月度请求数）。当月请求数用完后，高风险命令仍会被拦截，Agent 会说明原因；未经询问，不会放行任何命令。

安装。 将这台计算机连接到工作区一次：

npx -y @hibira-io/mcp-approval-gate login --label "coding agent"

然后添加钩子。使用 Hibira Agent 插件 市场：claude plugin install hibira-approval-hooks@hibira（Codex 和 Cursor 安装同一插件）。也可以手动添加：

• Claude Code，~/.claude/settings.json（或项目的 .claude/settings.json）：

  { "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [
    { "type": "command", "command": "npx -y @hibira-io/mcp-approval-gate hook claude", "timeout": 660 }
  ] } ] } }
  

• Codex，~/.codex/hooks.json（然后使用 /hooks 信任它）：

  { "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [
    { "type": "command", "command": "npx -y @hibira-io/mcp-approval-gate hook codex", "timeout": 660 }
  ] } ] } }
  

• Cursor，~/.cursor/hooks.json：

  { "version": 1, "hooks": { "beforeShellExecution": [
    { "command": "npx -y @hibira-io/mcp-approval-gate hook cursor", "timeout": 660, "failClosed": true }
  ] } }
  

• Hermes Agent，~/.hermes/config.yaml（Hermes 最多等待钩子 300 秒， 因此钩子会在等待 280 秒后停止等待，并告知 Agent 在获批后重试）。 Hibira Hermes 容器已完成此设置：

  hooks:
    pre_tool_call:
      - matcher: "terminal"
        command: "mcp-approval-gate hook hermes"
        timeout: 300
        fail_closed: true
  

若要更快地启动每条命令，可使用 npm install -g @hibira-io/mcp-approval-gate 安装一次，然后将 mcp-approval-gate hook claude 用作命令。

设置可写入 ~/.config/hibira/approval-hook.json 或通过环境变量配置：

{
  "always": ["^\\./scripts/ship\\.sh"],
  "never": ["^terraform apply .*-target=module\\.sandbox"],
  "approvers": ["platform-team"],
  "wait": 600,
  "expires": 30
}

GATE_HOOK=off 可在单个 Shell 会话中关闭钩子。项目可以在 .hibira/approval-hook.json 中添加自己的 always 规则和 approvers（但不能添加 never 规则，因此 Agent 无法通过编辑仓库关闭自身检查）。这是防止无心之失的安全网，并非沙箱：有意为之的 Agent 可以伪装命令，因此也应避免让 Agent 接触生产环境凭据。

选项

标志	环境变量	默认值
	HIBIRA_APPROVALS_TOKEN		工作区令牌，无需登录（服务器、容器）
--profile	GATE_PROFILE	default	使用哪个已保存的连接，以便将一台机器上的多个 gate 连接到不同的工作区
	HIBIRA_APP_ID, HIBIRA_KEY, HIBIRA_SECRET		改用 Hibira 应用的密钥，与 0.2 中一样（推送和频道选项适用于这些密钥）
	HIBIRA_API_URL	https://ws.hibira.io
--label	GATE_LABEL	database	审批页面上显示的数据库名称
--preset	GATE_PRESET		stripe、github、gmail 或 shopify（见上文）
--mode	GATE_MODE	writes	writes、all 或 none
--allow	GATE_ALLOW_TOOLS		无需等待的工具
--gate	GATE_TOOLS		始终需要等待的工具
--approvers	GATE_APPROVERS		在 Approvals 工作区中哪些人可以决定：审批人组的 slug 或成员的邮箱（默认：任何管理员或审批人）
--push-interests	GATE_PUSH_INTERESTS		将请求推送给这些兴趣群组
--push-users	GATE_PUSH_USERS		……或推送给这些用户 ID
--channel	GATE_CHANNEL		也在此频道上发布请求，例如用于审批收件箱
--show-link	GATE_SHOW_LINK	auto	向助手提供审批链接：auto（仅在没有推送或频道时）、always、never
--options	GATE_OPTIONS	Approve,Reject	答复按钮；第一个按钮表示批准
--wait	GATE_WAIT_SECONDS	50	调用等待多久后答复“仍在等待”
--expires	GATE_EXPIRES_MINUTES	60	请求保持开放的时长（最长 7 天）
-- <command>	GATE_COMMAND		要启动的数据库 MCP 服务
--upstream-url	GATE_UPSTREAM_URL		……或远程服务（Streamable HTTP）
--header	GATE_UPSTREAM_HEADERS		远程服务的请求头；${VAR} 会读取环境变量
--http		关闭	使用 Streamable HTTP 而非 stdio 提供服务
--host、--port	GATE_HOST、PORT	127.0.0.1、8787
	GATE_TOKEN		在非本地地址使用 --http 时必需

待处理的调用保存在 gate 的内存中。如果 gate 重启，等待中的调用会被遗忘（不会执行任何操作），助手只会再次询问。

开发

npm install
npm test
# against real servers and a local Postgres:
DATABASE_URL=postgres://... node --test test/real-servers.e2e.js

许可证

MIT

---

中文摘要

@hibira-io/mcp-approval-gate 套在任何数据库 MCP server（DBHub、postgres-mcp、Supabase MCP 等）外面：读取直接通过；写入、改表、删除会先停下，等另一个人（主管）在 Hibira 托管的审批页或手机推播上核准，核准后只按原样执行一次。

• 审批绑定这一次调用的完整参数（附指纹），SQL 改了就要重新审批。
• 设定了推播或频道时，助手拿不到审批链接，只有收到推播的主管能核准。
• 看不懂的 SQL、不确定是否只读的工具一律要审批；审批服务连不上就不执行。
• Gate 跑在你自己的环境，Hibira 只经手审批内容，不碰数据库密码，也看不到查询结果。
• Claude（Desktop / Code / claude.ai）、Cursor、ChatGPT 都能用；网页端用 --http 加 GATE_TOKEN。
• 设定：在 hibira.io 建立 Approvals 工作区并邀请审批人；设定里只要在 -- 后面接原本的数据库 MCP 指令，不用复制任何 Key。第一次要写入时，助手会给一个连接链接和代码，由工作区管理员登入后按「连接」即可（也可先执行 npx -y @hibira-io/mcp-approval-gate login）。
• 编码代理审批钩子（Claude Code / Codex / Cursor / Hermes Agent）：同一个套件也是 agent 的 hook。删档（rm -rf）、git push --force、部署（vercel --prod、fly deploy、wrangler deploy）、terraform apply、发包（npm publish）、数据库写入等不可逆的 shell 指令，会先送到 Approvals 工作区等另一个人核准，核准后只放行那一次；其他指令照常执行。先执行一次 npx -y @hibira-io/mcp-approval-gate login --label "coding agent"，再装 agent-plugin 里的 hibira-approval-hooks 插件（或照上面手动加 hook）。