superagent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Superagent

Set up Context Guardrails so external context is checked before a coding agent consumes it, connect the agent to Superagent over MCP, or configure signed webhooks. Keep credentials protected and avoid surprising the user with remote, billable, destructive, or policy-changing actions.

Superagent MCP is an authenticated remote service. Do not connect to it, send it data, or change an MCP client configuration unless the user explicitly asks.

Route setup requests by intent:

Context Guardrails setup or coding-agent hooks: follow Context Guardrails integration. Connecting MCP alone does not enforce pre-consumption checks.
Connect or troubleshoot Superagent MCP: follow MCP setup workflow.
Signed event delivery: follow Webhook setup.

设置 Context Guardrails，以便在 coding agent 读取外部上下文之前对其进行检查；通过 MCP 将 agent 连接到 Superagent；或配置签名 webhook。保护凭据，并避免远程、计费、破坏性或改变策略的操作给用户带来意外。

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

按意图分流设置请求：

Context Guardrails 设置或 coding-agent hooks：遵循 Context Guardrails 集成。仅连接 MCP 并不会强制执行读取前检查。
连接或排查 Superagent MCP：遵循 MCP 设置工作流。
签名事件交付：遵循 Webhook 设置。

MCP setup workflow

MCP 设置工作流

Identify the MCP client and whether the user wants a new connection, troubleshooting, or an operation on an existing connection.
For setup, direct the user to create an organization API key at Superagent Settings. Never ask them to paste the key into chat.
Store the key as
```
SUPERAGENT_API_KEY
```
in the user's shell or system environment. Never put it in a repository, tracked
```
.env
```
file, command output, or response.
Use the exact endpoint
```
https://www.superagent.sh/mcp
```
. The bare domain redirects, and some MCP clients fail on redirected POST requests.
Show the proposed configuration and obtain approval before editing client configuration or running a setup command.
Verify that the client connects and exposes Superagent tools before attempting a product operation.

An organization API key can access the entire organization. Prefer a dedicated, revocable key for agent use and revoke it immediately if it is exposed.

确定 MCP client，并判断用户是希望新建连接、排查问题，还是对现有连接执行操作。
对于设置，指导用户在 Superagent Settings 中创建组织 API key。绝不要要求用户将密钥粘贴到聊天中。
将密钥以
```
SUPERAGENT_API_KEY
```
存储在用户的 shell 或系统环境中。绝不要将其放入仓库、被跟踪的
```
.env
```
文件、命令输出或响应中。
使用精确的 endpoint
```
https://www.superagent.sh/mcp
```
。裸域名会重定向，且某些 MCP client 会在重定向后的 POST 请求上失败。
展示拟议配置，并在编辑 client 配置或运行设置命令前获得批准。
验证 client 已连接并公开 Superagent tools，然后才能尝试执行产品操作。

组织 API key 可以访问整个组织。优先为 agent 使用创建专用且可撤销的 key；如果该 key 暴露，应立即撤销。

Client configuration

Client 配置

Cursor

Add this server to

mcp.json

. Remote servers cannot read

envFile

, so

SUPERAGENT_API_KEY

must exist in the environment that launches Cursor.

json

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

将此 MCP server 添加到

mcp.json

。远程 server 无法读取

envFile

，因此

SUPERAGENT_API_KEY

必须存在于启动 Cursor 的环境中。

json

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

Claude Code

After confirming that

SUPERAGENT_API_KEY

is exported, propose:

bash

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

Run

/mcp

in Claude Code to confirm the connection.

确认

SUPERAGENT_API_KEY

已导出后，建议执行：

bash

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

在 Claude Code 中运行

/mcp

以确认连接。

Codex CLI

Add the following to

~/.codex/config.toml

. The feature flag must appear above every

[mcp_servers.*]

block. The token setting is the environment variable's name, not the token itself.

toml

experimental_use_rmcp_client = true

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

Export the variable before launching Codex, then use

/mcp

to verify.

将以下内容添加到

~/.codex/config.toml

。feature flag 必须位于每个

[mcp_servers.*]

block 之上。token 设置项填写的是环境变量名称，而不是 token 本身。

toml

experimental_use_rmcp_client = true

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

启动 Codex 前导出该变量，然后使用

/mcp

进行验证。

Other MCP clients

其他 MCP clients

Configure Streamable HTTP with:

URL:
```
https://www.superagent.sh/mcp
```

Header:

Authorization: Bearer $SUPERAGENT_API_KEY

Keep the token in the client's supported secret or environment-variable store, not in a tracked configuration file.

使用 Streamable HTTP 进行配置：

URL：
```
https://www.superagent.sh/mcp
```

Header：

Authorization: Bearer $SUPERAGENT_API_KEY

将 token 保存在 client 支持的 secret 或 environment-variable store 中，而不是被跟踪的配置文件里。

Operating Superagent

运维 Superagent

Inspect the connected server's available tools rather than assuming a fixed tool list. Match the user's request to these capability groups:

Findings: list and inspect findings, update manual triage, or request automated triage.
Reports: list or inspect repository, Web app, agent, and package reports; create a new report only after confirmation.
Contributor Trust: retrieve a cached result or start and check a scan.
Context Guardrails: score Web pages, email, files, skills, and public MCP repositories before an agent consumes them.
Runtime Guardrails: manage endpoint clients, groups, rules, built-in rule modes, and alerts.

Prefer the smallest read-only call that answers the question. Summarize the result and preserve identifiers the user needs for a follow-up. For asynchronous operations, report the returned status or identifier and avoid tight polling.

检查已连接 server 提供的可用 tools，不要假定工具列表固定。将用户请求与以下能力组进行匹配：

Findings：列出和检查 findings、更新人工 triage，或请求 automated triage。
Reports：列出或检查仓库、Web 应用、agent 和 package 报告；仅在确认后创建新报告。
Contributor Trust：获取缓存结果，或启动并检查扫描。
Context Guardrails：在 agent 读取网页、电子邮件、文件、skills 和公开 MCP repositories 之前对其进行评分。
Runtime Guardrails：管理 endpoint clients、groups、rules、内置 rule modes 和 alerts。

优先采用能够回答问题的最小只读调用。总结结果，并保留用户后续操作所需的 identifiers。对于异步操作，应报告返回的 status 或 identifier，避免频繁轮询。

Context Guardrails integration

Context Guardrails 集成

Distinguish a one-off scan from enforcement:

For "scan/check this URL, file, email, skill, or MCP repository," use the corresponding MCP tool.
For "add/enable/integrate Context Guardrails," install a check at the tool boundary before the agent consumes the context. A
```
SKILL.md
```
,
```
AGENTS.md
```
, rule, or system prompt is guidance, not enforcement.

Use this setup workflow:

Ask which context origins to protect, whether the setup is project-local or global, and whether an unavailable scanner should block the action. Recommend fail-closed for security-sensitive workflows and user-level or managed hooks for controls that use an organization API key. Use project hooks only in a trusted repository.
Inspect the client's current hook configuration and supported events. Merge with existing configuration; never replace it wholesale.
Gate the action that introduces context, before consumption: web-fetch and
```
curl
```
/
```
wget
```
actions for pages, download actions for public files, skill installation for skills, MCP add/install configuration for MCP repositories, and the inbound-message wrapper for email. Do not treat every later MCP tool call as a repository scan.
Map each selected origin to the narrowest client pre-execution boundary:
- Cursor:
```
preToolUse
```
  ,
```
beforeShellExecution
```
  , or
```
beforeMCPExecution
```
  .
- Claude Code:
```
PreToolUse
```
  matched to
```
WebFetch
```
  ,
```
Bash
```
  ,
```
Skill
```
  , or the relevant MCP tool.
- Codex CLI:
```
PreToolUse
```
  for supported local and MCP tools. Hosted
```
WebSearch
```
  is not hookable, so disclose that gap instead of claiming full coverage.
- Other clients: their equivalent before-tool hook, wrapper, middleware, or enforced rule plus an approved wrapper.
Show the exact hook, helper, paths, scope, verdict policy, outage behavior, and known coverage gaps. Obtain approval before writing files, changing client configuration, or sending a test target to Superagent.
For enforced hooks, install a small local helper that calls the Context Guardrails REST API with
```
SUPERAGENT_API_KEY
```
. Some clients support MCP-backed hook handlers, but a scan tool's result is not automatically a client-specific allow or deny decision, and MCP errors may fail open. Use MCP directly for interactive scans, not as the cross-client enforcement adapter. Keep the key in the environment, never in the helper or hook configuration. Prefer a user-controlled helper outside the repository and reference it by absolute path so repository code cannot silently replace it.
Test one allowed target and one blocked or unresolved target, then restart or reload the client if its hook system requires it. Use the client's hook inspector when available and verify the action itself was blocked, not merely that the helper printed a warning.

The helper must call the matching

/api/v1/context/*

endpoint:

Web page URL ->
```
GET /context/web_page/{identifier}
```
Public text or PDF URL ->
```
POST /context/file
```
Raw RFC 822 email ->
```
POST /context/email
```
skills.sh or public GitHub skill ->
```
POST /context/skill
```
Public GitHub MCP repository ->
```
POST /context/mcp
```

Skill and MCP scans support public GitHub targets only and require an active Superagent Security GitHub App installation. Verify that prerequisite before claiming those hook paths are enforced. Keep agent lifecycle hooks distinct from package, Git, or other install hooks found inside scanned content; the latter are threat signals.

Do not upload local private files through the public-URL file scanner, and get explicit authorization before sending raw email or other user content. Package and general repository scanning are not Context Guardrails origins: use Superagent supply-chain scanning for packages and repository reports for source repositories. Do not port an old package-install hook and claim that Context Guardrails scanned the package.

For an enforcement decision, parse the JSON response rather than relying only on score headers. Apply the selected tolerance consistently:

```
safe
```
: allow.
```
caution
```
: require user review unless the user explicitly chose a different policy.
```
suspicious
```
or
```
dangerous
```
: deny.
```
pending_deep_scan: true
```
, unscannable results, malformed responses, and scanner timeouts: treat as unresolved and follow the approved outage policy.

Do not let a preliminary identity score silently allow consumption while the deep scan is pending. Either request

mode=full

with a hook timeout long enough for completion, or block/ask and tell the agent to retry after the asynchronous scan finishes. Exempt the Superagent scanner calls themselves from generic MCP gates to avoid recursive checks.

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

对于“扫描或检查此 URL、文件、电子邮件、skill 或 MCP repository”，使用对应的 MCP tool。
对于“添加、启用或集成 Context Guardrails”，应在 agent 读取上下文之前，在工具边界安装检查。
```
SKILL.md
```
、
```
AGENTS.md
```
、rule 或 system prompt 属于指导机制，并非强制执行机制。

使用此设置工作流：

询问需要保护哪些上下文来源、设置是项目级还是全局级，以及 scanner 不可用时是否应阻止操作。对于安全敏感型工作流，推荐使用 fail-closed；对于使用组织 API key 的控制项，推荐使用用户级或托管 hooks。仅在受信任的仓库中使用 project hooks。
检查 client 当前的 hook 配置和受支持的事件。与现有配置合并；绝不要整体替换。
在引入上下文的操作执行前、且在读取上下文之前设置 gate：针对网页拦截 web-fetch 和
```
curl
```
/
```
wget
```
操作；针对公开文件拦截 download 操作；针对 skills 拦截 skill installation；针对 MCP repositories 拦截 MCP add/install configuration；针对电子邮件拦截 inbound-message wrapper。不要将之后的每次 MCP tool 调用都视为 repository scan。
将每个选定的来源映射到范围最窄的 client pre-execution boundary：
- Cursor：
```
preToolUse
```
  、
```
beforeShellExecution
```
  或
```
beforeMCPExecution
```
  。
- Claude Code：将
```
PreToolUse
```
  匹配到
```
WebFetch
```
  、
```
Bash
```
  、
```
Skill
```
  或相关的 MCP tool。
- Codex CLI：对受支持的本地 tools 和 MCP tools 使用
```
PreToolUse
```
  。托管的
```
WebSearch
```
  无法挂载 hook，因此应披露这一缺口，而不是声称具备完整覆盖。
- 其他 clients：使用其等效的 before-tool hook、wrapper、middleware，或 enforced rule 加 approved wrapper。
展示确切的 hook、helper、路径、scope、判定策略、不可用时的行为以及已知覆盖缺口。在写入文件、更改 client 配置或向 Superagent 发送测试目标之前获得批准。
对于 enforced hooks，安装一个调用 Context Guardrails REST API 并使用
```
SUPERAGENT_API_KEY
```
的小型本地 helper。部分 clients 支持 MCP-backed hook handlers，但 scan tool 的结果不会自动成为 client-specific 的 allow 或 deny 决策，而且 MCP errors 可能会 fail open。交互式扫描应直接使用 MCP，而不是将其作为跨客户端强制执行适配器。将 key 保留在 environment 中，绝不要放入 helper 或 hook 配置。优先使用 repository 之外、由用户控制的 helper，并通过绝对路径引用它，防止仓库代码在未察觉的情况下替换该 helper。
测试一个允许的目标和一个被阻止或无法解析的目标。如果 client 的 hook system 有此要求，则重启或重新加载 client。尽可能使用 client 的 hook inspector，并验证操作本身确实被阻止，而不只是 helper 打印了一条警告。

helper 必须调用匹配的

/api/v1/context/*

endpoint：

网页 URL ->
```
GET /context/web_page/{identifier}
```
公开文本或 PDF URL ->
```
POST /context/file
```
原始 RFC 822 电子邮件 ->
```
POST /context/email
```
skills.sh 或公开 GitHub skill ->
```
POST /context/skill
```
公开 GitHub MCP repository ->
```
POST /context/mcp
```

Skill 和 MCP 扫描仅支持公开 GitHub 目标，并要求已安装并启用 Superagent Security GitHub App。在声称这些 hook 路径已强制执行之前，务必验证此前提。将 agent lifecycle hooks 与扫描内容中发现的 package、Git 或其他 install hooks 区分开；后者属于威胁信号。

不要通过公共 URL 文件扫描器上传本地私有文件，并在发送原始电子邮件或其他用户内容前获得明确授权。Package 和常规仓库扫描不属于 Context Guardrails 来源：package 应使用 Superagent 供应链扫描，源代码仓库应使用仓库报告。不要移植旧的 package-install hook，并声称 Context Guardrails 已扫描该 package。

对于强制执行决策，应解析 JSON 响应，而不是仅依赖 score headers。一致应用选定的判定策略：

```
safe
```
：允许。
```
caution
```
：要求用户 review，除非用户明确选择了其他策略。
```
suspicious
```
或
```
dangerous
```
：拒绝。
```
pending_deep_scan: true
```
、无法扫描的结果、格式错误的响应和 scanner timeout：视为未解析，并遵循已批准的不可用处理策略。

不要在 deep scan 尚未完成时，让 preliminary identity score 静默允许读取上下文。要么使用 hook timeout 足够长的

mode=full

请求，要么阻止操作或请求用户审查，并告知 agent 在异步扫描完成后重试。将 Superagent scanner 对自身的调用排除在通用 MCP gates 之外，以避免递归检查。

Hook safety requirements

Hook 安全要求

Follow the installed client's current hook schema rather than copying one client's JSON response into another:

Use narrow, anchored tool matchers and command predicates. Broad hooks add latency and create bypasses or accidental blocks.
Parse stdin as structured JSON. Never use
```
eval
```
, shell interpolation, or string-built commands with untrusted tool input. URL-encode identifiers and pass values as quoted arguments or request bodies.
Emit only the client's documented decision JSON on stdout; send diagnostics to stderr. Treat malformed input and output as a security failure under the chosen outage policy.
Use one bounded HTTPS request with explicit connection and total timeouts. Do not log authorization headers, raw email, or response bodies containing user content.
Do not let hook configuration auto-approve an action that the client's normal permission system denies. Context Guardrails should only add restrictions.

Apply platform failure behavior explicitly:

Cursor: security hooks fail open on crashes, timeouts, and invalid JSON unless the hook sets
```
failClosed: true
```
. Set it for enforced boundaries.
```
permission: "ask"
```
is not enforced for
```
preToolUse
```
; when review is required, use a boundary that supports asking or deny with a clear review instruction.
Claude Code: use a
```
PreToolUse
```
denial response or exit code
```
2
```
for a hard block. A timed-out command, HTTP, or MCP-tool hook continues through normal permission flow, so timeout alone is not fail-closed. Keep normal permission rules in place as defense in depth.
Codex CLI: use the documented
```
PreToolUse
```
denial JSON or exit code
```
2
```
with the reason on stderr. Invalid fields and hook failures can continue the tool call. Hosted tools such as
```
WebSearch
```
remain outside hook coverage.

遵循已安装 client 当前的 hook schema，而不是将一个 client 的 JSON 响应复制到另一个 client：

使用范围窄且锚定的工具匹配器和命令谓词。宽泛的 hooks 会增加延迟，并造成绕过或意外阻止。
将 stdin 解析为结构化 JSON。绝不要对不可信的 tool input 使用
```
eval
```
、shell 插值或字符串拼接的命令。对 identifiers 进行 URL 编码，并将 values 作为带引号的参数或 request body 传递。
仅在 stdout 中输出 client 有文档说明的 decision JSON；将 diagnostics 发送到 stderr。在所选的不可用处理策略下，将格式错误的输入和输出视为安全故障。
发起一次有界 HTTPS 请求，并显式设置 connection timeout 和 total timeout。不要记录 Authorization headers、原始电子邮件或包含用户内容的响应正文。
不要让 hook 配置自动批准 client 正常 permission system 本应拒绝的操作。Context Guardrails 只能增加限制。

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

Cursor：除非 hook 设置了
```
failClosed: true
```
，否则 security hooks 在崩溃、超时和 JSON 无效时会 fail open。对于强制执行边界，应设置该选项。
```
permission: "ask"
```
不会对
```
preToolUse
```
强制执行；需要 review 时，应使用支持询问或拒绝的边界，并给出明确的 review 指示。
Claude Code：使用
```
PreToolUse
```
denial response 或退出码
```
2
```
实施硬性阻止。命令、HTTP 或 MCP-tool hook 超时后会继续进入正常权限流程，因此仅靠 timeout 无法实现 fail-closed。保留正常的权限规则，作为纵深防御。
Codex CLI：使用有文档说明的
```
PreToolUse
```
denial JSON 或退出码
```
2
```
，并将原因写入 stderr。字段无效和 hook failures 可能会继续执行 tool call。
```
WebSearch
```
等托管 tools 仍不在 hook 覆盖范围内。

Webhook setup

Webhook 设置

Use webhooks when the user wants Superagent events delivered to an agent, ticketing system, or remediation workflow. Webhook targets are configured at the organization level in Superagent Settings, not through the current MCP tool surface. Do not claim that an MCP call created or changed a webhook.

Before setup:

Ask which public HTTPS endpoint should receive events and which event types the user needs.
Confirm that the endpoint can preserve the raw request body, return a quick
```
2xx
```
response, and move longer work to an asynchronous queue.
Show the proposed target name, URL, and subscriptions. Obtain approval before using browser tools or another authenticated interface to create or modify the organization-wide target.

Guide the user through Settings → Webhooks → Add webhook. Enter the approved target name and HTTPS URL, select subscriptions, save, and copy the signing secret. The secret is shown only once. Never ask the user to paste it into chat, and never place it in source control, command output, logs, or a response. Store it in the receiver's secret manager or environment.

Supported subscriptions include:

```
report.started
```
and
```
report.finished
```

finding.created

finding.triage_completed

, and

finding.accepted

```
contributor_trust.finished
```

agent.finding_created

and

agent.action_blocked

The receiver must:

verify

X-Superagent-Signature

with HMAC-SHA256 over

<X-Superagent-Timestamp>.<raw-json-body>

using the signing secret;

compare signatures with a timing-safe operation;
deduplicate deliveries by
```
X-Superagent-Event-Id
```
or the payload
```
id
```
;
return a
```
2xx
```
quickly, because network errors,
```
408
```
,
```
429
```
, and
```
5xx
```
responses are retried.

After saving, send a test event from Settings and verify the signature, deduplication, and response path before enabling downstream automation. If the secret is exposed, regenerate it immediately and update the receiver.

当用户希望将 Superagent events 交付给 agent、ticketing system 或 remediation workflow 时，使用 webhooks。Webhook targets 在组织级别通过 Superagent Settings 配置，而不是通过当前的 MCP tool surface。不要声称 MCP call 创建或修改了 webhook。

设置前：

询问哪个公开 HTTPS endpoint 应接收 events，以及用户需要哪些 event types。
确认该 endpoint 能够保留原始请求正文、快速返回
```
2xx
```
响应，并将耗时较长的工作转移到异步队列。
展示拟议的 target name、URL 和 subscriptions。在使用 browser tools 或其他 authenticated interface 创建或修改组织级 target 之前获得批准。

指导用户进入 Settings → Webhooks → Add webhook。输入已批准的 target name 和 HTTPS URL，选择 subscriptions，保存，然后复制签名密钥。签名密钥仅显示一次。绝不要要求用户将其粘贴到聊天中，也绝不要将其放入源代码管理、命令输出、日志或响应中。将其存储在接收端的 secret manager 或 environment 中。

受支持的 subscriptions 包括：

```
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

；

使用 timing-safe 操作比较签名；
通过
```
X-Superagent-Event-Id
```
或 payload 的
```
id
```
对投递进行去重；
快速返回
```
2xx
```
，因为网络错误以及
```
408
```
、
```
429
```
和
```
5xx
```
响应都会触发重试。

保存后，从 Settings 发送一个测试 event，并验证签名、去重和响应路径，然后再启用下游自动化。如果密钥暴露，应立即重新生成并更新接收端。

Confirmation gates

确认关卡

Get explicit confirmation immediately before:

creating any report or running automated finding triage, because these consume organization credits;
permanently deleting a finding;
creating, updating, assigning, or deleting Runtime Guardrails clients, groups, or rules;
changing or restoring a built-in rule mode, because endpoint policy changes immediately;
creating, changing, disabling, rotating, or deleting an organization webhook target or its event subscriptions;
sending a target or content the user has not already authorized for remote analysis.

State the exact action, target, and consequence in the confirmation request. Tool annotations are hints, not a substitute for this gate.

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

创建任何报告或运行 automated finding triage，因为这些操作会消耗组织额度；
永久删除 finding；
创建、更新、分配或删除 Runtime Guardrails clients、groups 或 rules；
更改或恢复内置 rule mode，因为 endpoint 策略会立即生效；
创建、修改、禁用、轮换或删除组织 webhook target 或其 event subscriptions；
发送用户尚未授权进行远程分析的目标或内容。

在确认请求中说明确切的操作、目标和后果。Tool annotations 只是提示，不能替代此确认关卡。

Troubleshooting

故障排查

```
401 invalid_token
```
: verify the key is present, active, and sent as
```
Authorization: Bearer ...
```
.

or failed connection on

superagent.sh/mcp

: switch to

https://www.superagent.sh/mcp

Connected server with no tools: verify a proxy is not stripping the authorization header.
Codex server unavailable: put
```
experimental_use_rmcp_client = true
```
above all MCP server blocks and ensure
```
bearer_token_env_var
```
contains the variable name.
```
429
```
: wait for the server's
```
Retry-After
```
interval. Do not retry aggressively.

```
401 invalid_token
```
：验证 key 是否存在、是否有效，以及是否以
```
Authorization: Bearer ...
```
形式发送。

superagent.sh/mcp

或连接失败：切换到

https://www.superagent.sh/mcp

。

server 已连接但没有 tools：验证代理是否移除了 Authorization header。
Codex server 不可用：将
```
experimental_use_rmcp_client = true
```
放在所有 MCP server blocks 之上，并确保
```
bearer_token_env_var
```
中填写的是变量名称。
```
429
```
：等待服务器指定的
```
Retry-After
```
间隔。不要激进地重试。

superagent

Original

Translation

Superagent

Superagent

MCP setup workflow

MCP 设置工作流

Client configuration

Client 配置

Cursor

Cursor

Claude Code

Claude Code

Codex CLI

Codex CLI

Other MCP clients

其他 MCP clients

Operating Superagent

运维 Superagent

Context Guardrails integration

Context Guardrails 集成

Hook safety requirements

Hook 安全要求

Webhook setup

Webhook 设置

Confirmation gates

确认关卡

Troubleshooting

故障排查

Documentation

文档