superagent

Superagent

配置 Context Guardrails，在编码 Agent 使用外部上下文前对其进行检查；通过 MCP 将 Agent 连接到 Superagent；或配置已签名的 webhook。保护凭据，并避免在用户不知情的情况下执行远程、计费、破坏性或更改策略的操作。

Superagent MCP 是经过身份验证的远程服务。除非用户明确提出要求，否则不要连接该服务、向其发送数据或更改 MCP 客户端配置。

根据用户意图处理设置请求：

• 配置 Context Guardrails 或编码 Agent 钩子：按照 Context Guardrails 集成 中的说明操作。仅连接 MCP 不会强制执行使用前检查。
• 连接或排查 Superagent MCP 问题：按照 MCP 设置工作流 中的说明操作。
• 签名事件投递：按照 Webhook 设置 中的说明操作。

MCP 设置工作流

1. 确认 MCP 客户端，以及用户是要新建连接、排查问题，还是对现有连接执行操作。
2. 对于设置，请引导用户前往 Superagent 设置 创建组织 API 密钥。绝不要要求用户在聊天中粘贴密钥。
3. 将密钥存储为用户 Shell 或系统环境中的 SUPERAGENT_API_KEY。绝不要将其放入代码仓库、受版本控制的 .env 文件、命令输出或回复中。
4. 使用精确的端点 https://www.superagent.sh/mcp。裸域名会重定向，部分 MCP 客户端无法处理重定向后的 POST 请求。
5. 编辑客户端配置或运行设置命令前，展示拟议的配置并征得用户同意。
6. 确认客户端已连接并显示 Superagent 工具后，再尝试产品操作。

组织 API 密钥可访问整个组织。建议为 Agent 使用专用且可撤销的密钥；如果密钥泄露，请立即撤销。

客户端配置

Cursor

将此服务添加到 mcp.json。远程服务无法读取 envFile，因此 SUPERAGENT_API_KEY 必须存在于启动 Cursor 的环境中。

{
  "mcpServers": {
    "superagent": {
      "url": "https://www.superagent.sh/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SUPERAGENT_API_KEY}"
      }
    }
  }
}

Claude Code

确认已导出 SUPERAGENT_API_KEY 后，提出以下配置：

claude mcp add --transport http --scope user superagent https://www.superagent.sh/mcp \
  --header "Authorization: Bearer $SUPERAGENT_API_KEY"

在 Claude Code 中运行 /mcp，确认连接正常。

Codex CLI

将以下内容添加到 ~/.codex/config.toml。功能标志必须放在每个 [mcp_servers.*] 块之前。令牌设置项应填写环境变量的名称，而非令牌本身。

experimental_use_rmcp_client = true

[mcp_servers.superagent]
url = "https://www.superagent.sh/mcp"
bearer_token_env_var = "SUPERAGENT_API_KEY"

启动 Codex 前导出该变量，然后使用 /mcp 验证连接。

其他 MCP 客户端

配置 Streamable HTTP：

• URL：https://www.superagent.sh/mcp
• 标头：Authorization: Bearer $SUPERAGENT_API_KEY

将令牌保存在客户端支持的机密存储或环境变量存储中，不要放入受版本控制的配置文件。

使用 Superagent

检查已连接服务提供的工具，而不要假设工具列表固定不变。根据用户请求选择以下能力类别：

• 发现项：列出并检查发现项、更新人工分流结果，或请求自动分流。
• 报告：列出或检查仓库、Web 应用、Agent 和软件包报告；仅在确认后创建新报告。
• 贡献者信任度：获取缓存结果，或启动并检查扫描。
• Context Guardrails：在 Agent 使用网页、电子邮件、文件、技能和公开 MCP 仓库前为其评分。
• 运行时防护：管理端点客户端、分组、规则、内置规则模式和警报。

优先使用能够回答问题的最小只读调用。概述结果，并保留用户后续操作所需的标识符。对于异步操作，报告返回的状态或标识符，避免频繁轮询。

Context Guardrails 集成

区分一次性扫描和强制执行：

• 对于“扫描/检查此 URL、文件、电子邮件、技能或 MCP 仓库”，请使用相应的 MCP 工具。
• 对于“添加/启用/集成 Context Guardrails”，请在工具边界处、Agent 使用上下文之前安装检查机制。SKILL.md、AGENTS.md、规则或系统提示词只是指导，并不能强制执行。

请使用以下设置工作流：

1. 询问要保护哪些上下文来源、设置是仅限项目还是全局生效，以及扫描器不可用时是否应阻止操作。对于安全敏感的工作流，建议采用失败关闭策略；对于使用组织 API 密钥的控制，建议使用用户级或受管钩子。仅在可信仓库中使用项目钩子。
2. 检查客户端当前的钩子配置和支持的事件。与现有配置合并；绝不要整体替换。
3. 在引入上下文的操作处设置拦截，在使用上下文之前完成检查：网页的 web-fetch 和 curl/wget 操作、公共文件的下载操作、技能的安装操作、MCP 仓库的 MCP 添加/安装配置，以及电子邮件的入站消息包装器。不要把后续每次 MCP 工具调用都视为仓库扫描。
4. 将每个选定来源映射到范围最窄的客户端执行前边界：
   • Cursor：preToolUse、beforeShellExecution 或 beforeMCPExecution。
   • Claude Code：匹配 WebFetch、Bash、Skill 或相关 MCP 工具的 PreToolUse。
   • Codex CLI：针对受支持的本地工具和 MCP 工具使用 PreToolUse。托管的 WebSearch 无法挂钩，因此应说明这一覆盖缺口，而不是声称覆盖完整。
   • 其他客户端：使用其对应的工具调用前钩子、包装器、中间件，或已获批准的包装器加上强制规则。
5. 展示确切的钩子、辅助程序、路径、作用范围、判定策略、服务中断时的行为以及已知覆盖缺口。在写入文件、更改客户端配置或向 Superagent 发送测试目标之前，先获得批准。
6. 对于强制执行的钩子，安装一个精简的本地辅助程序，使用 SUPERAGENT_API_KEY 调用 Context Guardrails REST API。某些客户端支持由 MCP 承载的钩子处理程序，但扫描工具的结果不会自动成为特定客户端的允许或拒绝决定，而且 MCP 错误可能导致失败开放。交互式扫描可直接使用 MCP，但不要将其用作跨客户端强制执行适配器。密钥应保留在环境变量中，绝不要放入辅助程序或钩子配置。优先使用仓库外、由用户控制的辅助程序，并通过绝对路径引用，以防仓库代码暗中替换它。
7. 测试一个允许的目标，以及一个被阻止或尚未判定的目标；如果客户端的钩子系统有此要求，则重启或重新加载客户端。若有客户端钩子检查器，请使用它，并确认操作本身确实被阻止，而不只是辅助程序打印了警告。

辅助程序必须调用对应的 /api/v1/context/* 端点：

• 网页 URL -> GET /context/web_page/{identifier}
• 公共文本或 PDF URL -> POST /context/file
• 原始 RFC 822 电子邮件 -> POST /context/email
• skills.sh 或公共 GitHub 技能 -> POST /context/skill
• 公共 GitHub MCP 仓库 -> POST /context/mcp

技能和 MCP 扫描仅支持公共 GitHub 目标，并且需要已启用的 Superagent Security GitHub App 安装。声称这些钩子路径已强制执行之前，请先验证这一前提。区分 Agent 生命周期钩子与扫描内容中发现的程序包、Git 或其他安装钩子；后者是威胁信号。

不要通过公共 URL 文件扫描器上传本地私有文件；发送原始电子邮件或其他用户内容前，必须获得明确授权。程序包和通用仓库扫描并非 Context Guardrails 的来源：程序包应使用 Superagent 供应链扫描，源代码仓库应使用仓库报告。不要移植旧的程序包安装钩子，并声称 Context Guardrails 已扫描该程序包。 对于执行决策，应解析 JSON 响应，而不能只依赖评分标头。应一致地应用所选容差：

• safe：允许。
• caution：要求用户审核，除非用户明确选择了不同策略。
• suspicious 或 dangerous：拒绝。
• pending_deep_scan: true、无法扫描的结果、格式错误的响应和扫描器超时：视为未解决，并遵循已批准的故障策略。

深度扫描尚未完成时，不要让初步身份评分在不提示的情况下允许使用。应使用 mode=full，并将钩子超时设置得足够长以等待扫描完成；或者阻止/请求确认，并告知 Agent 在异步扫描完成后重试。将 Superagent 扫描器调用排除在通用 MCP 门控之外，以避免递归检查。

钩子安全要求

遵循已安装客户端当前的钩子架构，不要将某个客户端的 JSON 响应照搬到另一个客户端：

• 使用范围明确且锚定的工具匹配器和命令谓词。范围过宽的钩子会增加延迟，并造成绕过或意外阻止。
• 将 stdin 解析为结构化 JSON。绝不使用 eval、shell 插值，或用不可信工具输入拼接命令。对标识符进行 URL 编码，并将值作为带引号的参数或请求正文传递。
• stdout 仅输出客户端文档规定的决策 JSON；诊断信息发送到 stderr。根据所选故障策略，将格式错误的输入和输出视为安全故障。
• 仅发起一次有界 HTTPS 请求，并明确设置连接超时和总超时。不要记录授权标头、原始电子邮件地址，或包含用户内容的响应正文。
• 不要让钩子配置自动批准客户端常规权限系统拒绝的操作。Context Guardrails 只能增加限制。

明确应用各平台的故障行为：

• **Cursor：**钩子崩溃、超时或 JSON 无效时，安全钩子默认故障放行，除非钩子设置了 failClosed: true。对于强制执行的边界，应设置该选项。permission: "ask" 对 preToolUse 不具有强制效果；需要审核时，应使用支持请求确认的边界，或直接拒绝并给出明确的审核说明。
• **Claude Code：**硬性阻止时，使用 PreToolUse 拒绝响应或退出代码 2。命令、HTTP 或 MCP 工具钩子超时后，操作仍会进入常规权限流程，因此仅靠超时无法实现故障关闭。保留常规权限规则作为纵深防御。
• **Codex CLI：**使用文档规定的 PreToolUse 拒绝 JSON，或使用退出代码 2 并将原因写入 stderr。字段无效和钩子故障可能导致工具调用继续。WebSearch 等托管工具不在钩子覆盖范围内。

Webhook 设置

当用户希望将 Superagent 事件发送到 Agent、工单系统或修复工作流时，请使用 Webhook。Webhook 目标需在组织级别通过 Superagent Settings 配置，当前 MCP 工具界面不支持配置。不要声称 MCP 调用创建或更改了 Webhook。

设置前：

1. 询问要接收事件的公开 HTTPS 端点，以及用户需要哪些事件类型。
2. 确认该端点能够保留原始请求正文、快速返回 2xx，并将较耗时的工作转入异步队列。
3. 显示拟配置的目标名称、URL 和订阅项。使用浏览器工具或其他经过身份验证的界面创建或修改组织级目标前，先征得用户批准。

指导用户依次进入 Settings → Webhooks → Add webhook。输入已获批准的目标名称和 HTTPS URL，选择订阅项，保存并复制签名密钥。该密钥只会显示一次。切勿要求用户将其粘贴到聊天中，也不要将其写入源代码管理、命令输出、日志或回复中。请将其存储在接收端的密钥管理器或环境中。

支持的订阅包括：

• report.started 和 report.finished
• finding.created、finding.triage_completed 和 finding.accepted
• contributor_trust.finished
• agent.finding_created 和 agent.action_blocked

接收端必须：

• 使用签名密钥，对 <X-Superagent-Timestamp>.<raw-json-body> 计算 HMAC-SHA256，以验证 X-Superagent-Signature；
• 使用时序安全操作比较签名；
• 根据 X-Superagent-Event-Id 或载荷中的 id 对投递进行去重；
• 快速返回 2xx，因为网络错误、408、429 和 5xx 响应都会触发重试。

保存后，在 Settings 中发送测试事件，并在启用下游自动化之前验证签名、去重和响应路径。如果密钥泄露，请立即重新生成，并更新接收端。

确认门槛

执行以下操作前，须立即获得明确确认：

• 创建任何报告或运行自动发现项分类，因为这些操作会消耗组织额度；
• 永久删除发现项；
• 创建、更新、分配或删除 Runtime Guardrails 客户端、组或规则；
• 更改或恢复内置规则模式，因为端点策略会立即发生变化；
• 创建、更改、禁用、轮换或删除组织 Webhook 目标或其事件订阅；
• 将用户尚未授权进行远程分析的目标或内容发送出去。

在确认请求中说明确切的操作、目标和后果。工具注释只能作为提示，不能替代此确认门槛。

故障排除

• 401 invalid_token：检查密钥是否存在且处于启用状态，并确认已通过 Authorization: Bearer ... 发送。
• 在 superagent.sh/mcp 上出现 404 或连接失败：改用 https://www.superagent.sh/mcp。
• 服务已连接但没有工具：检查代理是否剥除了授权标头。
• Codex 服务不可用：将 experimental_use_rmcp_client = true 放在所有 MCP 服务配置块之前，并确保 bearer_token_env_var 包含变量名称。
• 429：等待服务端指定的 Retry-After 时长。不要频繁重试。

文档

• MCP 服务
• API 概览
• 设置和 API 密钥
• Webhook
• 发现结果
• 红队报告
• 上下文护栏
• 上下文护栏 API
• Cursor 钩子
• Claude Code 钩子
• Codex CLI 钩子