设置
将 AI 助手连接到 Waafir 只需要一个 URL:把它粘贴到您的助手中,然后在助手提示时登录 Waafir。无需创建或复制任何令牌。本页介绍登录过程、各助手添加服务器的步骤,以及当助手无法登录时如何改用个人访问令牌进行连接。
基础知识
URL。 一个 URL 即可提供所有 Waafir 工具:
https://app.waafir.io/api/mcp/waafir附加功能 → 配置 → AI助手 会显示适用于您部署环境的 URL,并附带复制按钮。如果您使用的是其他部署环境,请替换 https://app.waafir.io。
登录。 您的助手第一次使用该 URL 时,会在浏览器中打开 Waafir。像平常一样登录,然后查看授权同意页面:
- 哪个组织:如果您属于多个组织,选择助手在哪个组织中工作;
- 哪些数据室:它可以访问全部数据室,还是仅限您选定的数据室;
- 它可以做什么:读取、写入或管理员权限,绝不会超出您自身角色所允许的范围,以及它是否可以签署文档或向组织外部发送;
- 确认是您本人。 如果您设置了双因素认证,每次批准都会先要求您输入验证码,与创建令牌时一样。
批准后,浏览器会将您交还给助手。该连接会出现在 附加功能 → 配置 → AI助手 下,您可以在那里查看它能访问的内容并撤销它。请参阅连接。
Unverified app "…"。 通过其所控制的网址来标识自身的助手,会以该网址显示,例如 claude.ai。以自行选择的名称注册的助手会显示为 Unverified app "<its name>":Waafir 无法确认它的制作者,因此只有在连接是由您本人发起时才应批准它。
工具列表显示的内容。 工具名称以其领域开头:dataroom_、esign_、redact_ 和 translate_。列表只显示您的连接和您的组织可以使用的工具:只读连接看不到写入工具,而电子签名工具只有在您的组织拥有 E-Signatures 附加功能或有效订阅时才会出现。连接还会列出那些需要您未授予之权限的工具,例如签署或向组织外部发送。如果助手调用了其中一个,Waafir 会拒绝该调用,助手会请您再次批准,这一次会提供该权限供您选择。令牌无法再次请求,因此其列表中不包含这些工具。未列出的工具,如果助手仍然调用,也会被拒绝并说明原因。
连接您的助手
下面各节给出了每个助手自己的添加服务器步骤,并附有其文档链接(每个链接最近一次检查于 2026 年 10 月 23 日)。这些助手都尚未经过 Waafir 登录测试,因此每节都附带了令牌备用方案。
Claude(claude.ai 和 Claude Desktop)
尚未由 Waafir 测试。 打开 Customize → Connectors,选择 Add → Add custom connector,为其命名,粘贴 URL,然后继续。保持登录开启,并在 Claude 提示时登录 Waafir。要在聊天中使用它,请在 + → Connectors 下将其开启。在 Team 或 Enterprise 套餐中,由所有者在 Organization settings → Connectors 下添加连接器。(Claude 的指南)
如果登录不起作用,请改为添加一个带令牌的请求头 Authorization: Bearer <token>(请参阅改用令牌连接)。
ChatGPT
尚未由 Waafir 测试。 根据应用的不同,ChatGPT 访问远程 MCP 服务器的入口位置也不同;在桌面应用中,打开 Settings → MCP servers → Add server 并粘贴 URL,然后在提示时登录 Waafir。(OpenAI 的指南)
如果 ChatGPT 无法登录,请改用令牌。
Claude Code
尚未由 Waafir 测试。
claude mcp add --transport http waafir https://app.waafir.io/api/mcp/waafir然后在 Claude Code 中运行 /mcp(或在 shell 中运行 claude mcp login waafir),并在浏览器中登录 Waafir。添加 --scope user 可在所有项目中使用它。附加功能 → 配置 → AI助手 中提供了可直接复制的该命令。(Claude Code 的指南)
Cursor
尚未由 Waafir 测试。 将 URL 添加到 .cursor/mcp.json(或者添加到 ~/.cursor/mcp.json 以用于所有项目),然后在 Cursor 提示时登录 Waafir:
{
"mcpServers": {
"waafir": {
"url": "https://app.waafir.io/api/mcp/waafir"
}
}
}如果 Cursor 无法登录,请添加改用令牌连接中所示的令牌请求头。
VS Code
尚未由 Waafir 测试。 从命令面板运行 MCP: Add Server,选择 HTTP,粘贴 URL,并将其 id 设为 waafir。在 VS Code 提示时登录 Waafir。(VS Code 的指南)
Gemini CLI
尚未由 Waafir 测试。
gemini mcp add --transport http waafir https://app.waafir.io/api/mcp/waafir然后运行 /mcp auth waafir 并在浏览器中登录。登录需要本地浏览器,因此在大多数远程 SSH 会话中无法使用:在这种情况下请使用令牌。(Gemini CLI 的指南)
Codex
尚未由 Waafir 测试。
codex mcp add waafir --url https://app.waafir.io/api/mcp/waafir
codex mcp login waafir改用令牌连接
当助手无法登录,或用于脚本时,请使用个人访问令牌。每个请求都在 Authorization 请求头中以 bearer 令牌 的形式携带该令牌:
Authorization: Bearer waafir_pat_...切勿将真实令牌提交到共享文件或代码仓库中;请像对待密码一样对待它。附加功能 → 配置 → API令牌 中提供了可直接复制的代码片段。
领域服务器。 除了 waafir 之外,四个领域服务器仍在提供服务,因此现有配置可以继续使用。每个领域服务器只列出自己领域的工具,以同样的方式筛选,并保留一直以来的工具名称(list_files 而不是 dataroom_list_files)。如果您连接的是 waafir,则不需要它们:
| 服务器 | URL |
|---|---|
waafir-redact | https://app.waafir.io/api/mcp/waafir-redact |
waafir-translate | https://app.waafir.io/api/mcp/waafir-translate |
waafir-dataroom | https://app.waafir.io/api/mcp/waafir-dataroom |
waafir-esign | https://app.waafir.io/api/mcp/waafir-esign |
不存在单独的 /api/mcp 端点:服务器名称段是必需的,不带它的请求会返回 404。waafir-esign 是一项付费服务:没有 E-Signatures 附加功能或有效订阅时,其 URL 会返回 ADDON_NOT_PURCHASED 错误。在 waafir 上,同一组织只是看不到 esign_ 工具。
Claude Code。 先将令牌放入环境变量,使其不会留在 shell 历史记录中:
export WAAFIR_PAT=... # the token you copied at issuance
claude mcp add --transport http waafir https://app.waafir.io/api/mcp/waafir \
--header "Authorization: Bearer $WAAFIR_PAT"若要与项目共享该设置,请将同样的条目放入项目的 .mcp.json。Claude Code 会从每个人的环境中展开 ${WAAFIR_PAT},因此该文件可以在不含令牌的情况下提交:
{
"mcpServers": {
"waafir": {
"type": "http",
"url": "https://app.waafir.io/api/mcp/waafir",
"headers": {
"Authorization": "Bearer ${WAAFIR_PAT}"
}
}
}
}Claude Desktop 的配置文件。 claude_desktop_config.json 启动的是本地服务器:每个条目都是要运行的 command,而不是远程 url。若要从该文件访问 Waafir,请运行 mcp-remote 桥接程序(需要 Node.js),它会转发到远程服务器,并将您的令牌添加为请求头:
{
"mcpServers": {
"waafir": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://app.waafir.io/api/mcp/waafir",
"--header",
"Authorization:${WAAFIR_AUTH}"
],
"env": {
"WAAFIR_AUTH": "Bearer YOUR_WAAFIR_PAT"
}
}
}
}确保 Authorization:${WAAFIR_AUTH} 参数中不含空格,然后重启 Claude Desktop。
Cursor,以及其他接受 URL 和请求头的客户端。
{
"mcpServers": {
"waafir": {
"url": "https://app.waafir.io/api/mcp/waafir",
"headers": {
"Authorization": "Bearer YOUR_WAAFIR_PAT"
}
}
}
}领域服务器的添加方式相同,只需更改条目键名和 URL。
调用工具
连接后,您的客户端会列出服务器的工具(MCP tools/list),并代表您调用它们。您不需要手动调用工具:您只需让 AI 客户端做某件事(“列出此数据室中的文件”“把这段话翻译成法语”),它就会选择并调用合适的工具,并传入各服务器参考文档中记载的参数。工具约定请参阅 waafir-redact、waafir-translate、waafir-dataroom 和 waafir-esign 参考。
出现问题时
失败会出现在两个不同的层上,而且它们看起来并不相同。搞错这一点是此处最常见的集成错误:只根据 HTTP 状态进行分支的客户端,会悄无声息地漏掉第二类的所有失败。
第 1 层 — 请求在任何工具运行之前就被拒绝
这些是真正的 HTTP 错误状态,带有 JSON-RPC 格式的错误正文。它们表示请求根本没有到达任何工具:
-
404 — 未知的 MCP 服务器。 URL 中的服务器名称段不是
waafir、waafir-redact、waafir-translate、waafir-dataroom或waafir-esign之一,最常见的原因是拼写错误,或使用了不带服务器名称的单独/api/mcp。请修正 URL。 -
402 — 未购买附加功能。 该服务器是付费服务(目前为
waafir-esign),而您的组织既没有该附加功能,也没有有效订阅。组织管理员可以在账单设置中购买该附加功能或套餐。没有权益的组织甚至无法列出该服务器的工具。waafir永远不会返回 402:它会改为隐藏付费工具,对其中某个工具的调用会在第 2 层以QUOTA_EXCEEDED被拒绝,并附带指明该工具的消息,该消息中也包含ADDON_NOT_PURCHASED。 -
401 — 未认证。 凭据缺失、格式错误、已撤销或已过期。对于连接,请从您的助手重新登录:大多数助手在看到 401 时会自动为您完成这一步,而已被撤销或连续 30 天未使用的连接需要重新登录。对于令牌,请检查
Authorization请求头是否存在,以及该令牌在 附加功能 → 配置 → API令牌 中是否仍处于有效状态;如果它已被撤销或已过期,请签发一个新的令牌。早于此行为的部署环境在令牌缺失或格式错误时,会改为返回 403CSRF validation failed: missing Origin;在此接口上,这同样表示令牌缺失或格式错误。 -
403 — 禁止访问。 凭据在入口处就被拒绝:使用了已登录的浏览器会话,而不是连接或 PAT(此接口不接受会话),或者您的组织强制执行 IP 允许列表,而请求来自列表之外的地址。
-
429 — 请求过多。 您触发了 MCP 速率限制。这里没有任何限制是按您的 IP 地址或您的组织计算的:您的额度属于您的令牌,因此同一组织中的同事以及同一网络上的第二个客户端都不会消耗它。限制为每个令牌每分钟 60 个请求。该计数在查找令牌之前进行,因此格式错误、已撤销或已过期的令牌也会消耗额度,并且同一令牌在 MCP 之外对 Waafir API 的调用也计入同样的 60 次。已登录连接的 60 次还按连接计算,因此助手刷新登录时获得的新令牌不会重新开始计算 60 次。
响应中没有
Retry-After请求头,也没有用于区分的代码(此接口上的每个 429 看起来都一样),因此请按照您自己的时间表退避,而不是不停重试。如果一个令牌的余量不够,请签发第二个:限制是按令牌计算的。
第 2 层 — 工具已运行并拒绝
大多数拒绝都发生在这一层,而且它不是 HTTP 错误。 HTTP 响应为 200,JSON-RPC 信封是一个成功信封。失败信息包含在工具结果中,该结果设置了 isError: true,其文本内容为:
{ "error": { "code": "CONFLICT", "message": "…" } }请根据 error.code 进行分支。代码如下:
| 代码 | 含义 |
|---|---|
INVALID_ARGUMENT | 某个参数缺失、格式错误或不是有效的 id:请修正后重试 |
FORBIDDEN | 令牌有效,但不允许执行此调用 |
NOT_FOUND | 没有这样的记录,或该记录不属于您 |
CONFLICT | 请求已被理解且被允许,但数据室当前的状态无法执行该操作 |
TOO_LARGE | 输入超出大小限制:请拆分 |
QUOTA_EXCEEDED | 计量额度已用完;需要有人购买或升级某项内容 |
UPSTREAM_ERROR / UNAVAILABLE | 暂时性的下游故障:请稍后重试 |
INTERNAL | 意外故障:请勿重试,请上报 |
其中有两种容易让人误解:
- 权限范围过低时返回的
FORBIDDEN。read连接或令牌看不到写入工具,但仍然调用写入工具的客户端会被工具本身拒绝,因此它会以载荷中的FORBIDDEN出现在这一层,而不是 HTTP 403。对于限定于特定数据室的令牌,如果它将允许列表之外的数据室作为dataroom_id传入,情况也是如此。大多数接受文件或文件夹 id 的工具,对于此类数据室中的项目则会返回NOT_FOUND,与 id 不存在时完全相同。请从您的助手重新登录并授予正确的权限范围或数据室,或者签发一个具有正确权限范围的令牌。 CONFLICT。 调用已被理解且被允许,但数据室当前的状态无法执行该操作:例如文件夹名称已被占用、文件的名称已被另一个现存文件占用,或者要恢复的项目其所在容器仍处于已删除状态、或其上传从未完成。CONFLICT不是授权问题,重新登录或重新签发令牌都无济于事;如果存在造成阻塞的记录,消息会指明该记录,以便您处理后重试。waafir-dataroom参考列出了每个工具可能返回的冲突。
仍在检查中的文件。 Waafir 会在提供内容之前检查每个新上传的文件和每个新版本。在此之前,读取该文件内容的工具会返回 UNAVAILABLE,附带 error.reason: "ACTIVATION_PENDING" 和消息 This file is still being checked. Try again shortly. 这是暂时性的:请稍等片刻后再次调用。
无论在哪一层,明确的拒绝都是 Waafir 不会执行的调用所预期的、安全的结果:它会让请求失败,而不是悄无声息地少做您要求的事情。