BLACK_WALL — Pre-action risk gate for AI agents

blackwall-mcp

作为 MCP 服务，为 AI Agent 提供安全护栏。 在执行任何不可逆操作（发送邮件、转移资金、运行 SQL、删除数据、发布内容）之前，Agent 都会调用一个工具——forecast。几秒钟内（约 4–8 秒），它会返回风险评分（0–100）、可逆性类别、GO / CAUTION / STOP 建议，以及明确列出的风险信号。

适用于任何 MCP 宿主：Claude Desktop、Claude Code、Cursor、Windsurf，以及任何支持 MCP 的 Agent 框架。

您的 Agent 与灾难之间的防护墙。BLUETIER 产品。

---

1. 获取 API 密钥

前往 https://blackwalltier.com 免费注册 → Dashboard → API keys → Create key。 免费套餐：每月约 100 次预测，无需绑定银行卡。您的密钥格式为 bw_live_…。

2. 将服务添加到 MCP 宿主

Claude Desktop

编辑 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "blackwall": {
      "command": "npx",
      "args": ["-y", "blackwall-mcp"],
      "env": { "BLACKWALL_API_KEY": "bw_live_your_key_here" }
    }
  }
}

重启 Claude Desktop。您将看到可用的 forecast 工具。

Cursor

Settings → MCP → Add new global MCP server，然后在 mcp.json 中：

{
  "mcpServers": {
    "blackwall": {
      "command": "npx",
      "args": ["-y", "blackwall-mcp"],
      "env": { "BLACKWALL_API_KEY": "bw_live_your_key_here" }
    }
  }
}

Claude Code

claude mcp add blackwall -e BLACKWALL_API_KEY=bw_live_your_key_here -- npx -y blackwall-mcp

本地运行（适用于任何宿主／测试）

BLACKWALL_API_KEY=bw_live_your_key_here npx -y blackwall-mcp

3. 使用

添加完成后，向 Agent 发出指示：“执行任何不可逆操作之前，调用 forecast 工具；如果它返回 STOP，就停止操作。” 模型即将执行有风险的操作时，会自动调用该工具。

---

forecast 工具

参数	类型	必填	说明
action	string	✅	操作类型，例如 send_email、make_payment、run_sql、delete_file、post_content
inputs	object	✅	具体参数：收件人、amount_usd、SQL statement、文件路径、消息正文、URL 等
context	object	—	可选：{ agent_role, user_intent, environment }
depth	standard | deep	—	分析深度。默认值为 standard。

返回： 建议（GO/CAUTION/STOP）、risk_score（0–100）、reversibility（类别和回滚成本）、gate（继续／确认／需要人工处理）、confidence、red_flags[]、predicted_result、alternative_actions[]。

示例

Agent 即将运行 DELETE FROM users;（没有 WHERE 子句） →

🛑 BLACK_WALL: STOP — risk 99/100
Red flags:
  • [CRITICAL] SQL_NO_WHERE — deletes the entire table, not one row
  • [CRITICAL] INTENT_MISMATCH — intent was "remove a single test row"
  • [CRITICAL] IRREVERSIBLE_NO_BACKUP — no recovery path
Guidance: DO NOT take this action. Surface the red flags to the user.

---

观察模式——零风险试用

还不想让安全护栏拦截 Agent？可以先启用观察模式。它会为每个操作评分并记录日志，但绝不会指示 Agent 停止——您的 Agent 会像现在一样正常运行。一周后，查看 Dashboard，看看它本来会拦截哪些操作。

{
  "mcpServers": {
    "blackwall": {
      "command": "npx",
      "args": ["-y", "blackwall-mcp"],
      "env": {
        "BLACKWALL_API_KEY": "bw_live_your_key_here",
        "BLACKWALL_MODE": "observe"
      }
    }
  }
}

然后在 Dashboard 中查看*“您的 Agent 差点执行的操作”*。准备好实际拦截操作时，将 BLACKWALL_MODE 切换为 enforce（或直接移除该变量——enforce 是默认值）。

两种工具

该服务提供两种 MCP 工具：

• forecast — 操作前风险检查。返回 GO / CAUTION / STOP、风险评分、明确列出的风险信号、可逆性类别，以及可验证的回执。
• observe — 操作后结果报告。告知 BLACK_WALL 操作执行后（或 Agent 遵从 STOP 判定后）实际发生了什么。借此闭合反馈环，让系统能够持续追踪预测准确度。免费——不扣除代币。

配置 Agent，使其在任何不可逆操作之前调用 forecast，然后使用原始响应中的 forecast_id 调用 observe。observe 接受 outcome_class（matched / over_scope / under_scope / no_op / diverged / aborted），以及可选的 divergence_severity 和 details。请参阅下方的 forecast 示例；observe 的配置方式相同。

在代码中使用 — gate() 控制（适用于任何 JS/TS Agent）

在 Node 中运行 Agent（LangChain、自定义循环、ElizaOS、cron 作业）？你不需要 MCP 宿主——直接从库中调用 BLACK_WALL，并让 gate() 确保检查绝不可能被跳过。只需一层封装，即可预测操作、执行判定（遇到 STOP / 未知判定 / 无法连接时默认拒绝）、仅在允许时运行副作用，并自动通过 observe 报告实际结果。

npm i blackwall-mcp

import { gate, BlackWallBlocked } from 'blackwall-mcp/lib/gate';

// Wrap ANY risky action in a few lines. BLACKWALL_API_KEY lives in the env.
try {
  const { result } = await gate(
    { action: 'run_sql', inputs: { statement: sql }, context: { user_intent } },
    () => db.query(sql),                        // your real side effect — only runs if allowed
    { onCaution: (v) => confirmWithHuman(v) },  // CAUTION needs a yes; default = block
  );
  // ...use result
} catch (e) {
  if (e instanceof BlackWallBlocked) {
    // STOP, unconfirmed CAUTION, or forecast unavailable → the action NEVER ran
    console.error('Blocked:', e.reason, e.verdict?.red_flags);
  } else throw e; // a real error thrown by your action
}

默认拒绝是设计如此。 如果无法获取判定（网络 / 身份验证 / 超时），除非你明确传入 failOpen: true，否则不会运行该操作。默认放行的风险关卡就不是真正的风险关卡。循环会自行闭合——gate() 会通过 observe 传入实际结果（matched / diverged / aborted），让预测随着时间推移越来越准确。

更倾向使用底层组件？它们也已导出：

import { forecast, observe } from 'blackwall-mcp/lib';

const v = await forecast({ action: 'make_payment', inputs: { amount_usd: 50000 } });
if (v.recommendation === 'STOP') throw new Error('halt');
// ... take the action ...
await observe(v.id, { outcome_class: 'matched' });

可运行的演示：examples/gate-quickstart.mjs。

决策凭证（加密，可离线验证）

每个 forecast 响应现在都包含一个 receipt 字段——它是对请求和响应的规范 SHA-256 哈希进行的 Ed25519 签名。任何拥有已发布公钥的人都可以离线验证 BLACK_WALL 是否批准了特定的（请求、响应）对，而无需信任我们的服务。

• 已发布的密钥：**https://blackwalltier.com/.well-known/blackwall-signing-keys.json**（稳定，可缓存）
• 无状态验证端点：使用 { envelope, request_body, response_body } 调用 POST https://blackwalltier.com/api/v1/receipts/verify
• 仅包含哈希——BLACK_WALL 从不存储原始请求 / 响应正文，因此凭证可提供加密审计，同时不暴露有效载荷
• 免费套餐保留期：90 天。付费套餐：永久。

MCP 服务会在工具输出中提供凭证 ID，供你的 Agent 记录，以便日后重放 / 审计。

配置参考

环境变量	必需	默认值	说明
BLACKWALL_API_KEY	✅	—	从控制面板获取的 bw_live_…
BLACKWALL_BASE_URL	—	https://blackwalltier.com
BLACKWALL_MODE	—	enforce	observe = 仅记录，从不阻止

链接

• 网站和文档：https://blackwalltier.com
• 获取密钥：https://blackwalltier.com/dashboard/keys

采用 MIT 许可证。