FairValid

开发者

通过 MCP 连接 AI 智能体

设置 ChatGPT、Claude、Hermes、Grok 或 Codex，检查连接状态，并控制验证支出。

管理 API 密钥API 参考

选择您的客户端

端点：https://mcp.fairvalid.com/mcp。传输方式：Streamable HTTP。

使用 API 密钥或 OAuth 登录进行连接。符合条件的 ChatGPT、Claude 和 Grok 连接可使用 OAuth；请在下方查看您的客户端对账户和角色的要求。Codex、Claude Code 和 Hermes 也支持直接使用 API 密钥连接。

对于使用 API 密钥的客户端，请以工作区所有者或管理员身份在 API 密钥 中创建一个带标签的 Test 密钥。将其保存在客户端受保护的凭据或文档所述的环境设置中。切勿将密钥放入提示词、工具参数、URL 或已提交的配置中。

OAuth 流程会打开 fairvalid.com 进行登录和授权。你可以选择一个涵盖所需权限的现有正式 API 密钥，并查看其所属工作区和总上限。批准后将一并授予所请求的权限，范围不超出该密钥的权限范围。此流程不会要求你将该密钥粘贴到 AI 客户端中。撤销所选密钥也会终止其所有连接。OAuth 使用正式密钥；如需使用沙盒，请通过测试密钥直接连接。

客户端说明已于 2026 年 10 月 23 日审核。托管 MCP 协议已通过官方 SDK 的生产验收测试。但这并不代表所列的每个客户端都经过了测试；请先在您的客户端中完成连接检查，再依赖其使用。

ChatGPT

请使用下方的 OAuth 设置。目前，自定义 MCP 连接需要网页版 ChatGPT Business 或 Enterprise/Edu，并具有创建含 MCP 插件的权限。Business 需要管理员或所有者；Enterprise/Edu 可授权指定成员。

  1. 打开“插件”，点击加号按钮，然后选择“添加自定义 MCP 服务器”。当前的插件流程无需开启开发者模式。
  2. 将连接命名为 FairValid，并输入 https://mcp.fairvalid.com/mcp 作为公共 HTTPS 端点。
  3. 请选择支持自动客户端注册的 OAuth。FairValid 采用公共客户端注册方式：您无需提供客户端 ID 或客户端密钥。切勿在任一字段中输入 API 密钥。
  4. 请完成上述 FairValid 登录和授权同意。查看 ChatGPT 的警告后，选择“创建为插件”，并检查发现的六个工具。
  5. 安装插件后，打开新对话，输入 @ 并选择 FairValid。在请求实时验证之前，请先运行下方的只读连接检查。

官方文档：OpenAI：连接自定义 MCP 服务器 · OpenAI：OAuth 身份验证

Claude 网页版和桌面版

使用支持 OAuth 的远程自定义连接器。这与 Claude 网页版和桌面版使用的账户关联连接相同，通过 Anthropic 的服务器运行。在 Team 和 Enterprise 版中，需由组织所有者先添加该连接器。拥有可管理组织库的自定义角色的 Enterprise 成员也可以添加。

Some organizations have a Request headers beta. For that alternative, choose No sign-in and add a required Authorization header with the full value Bearer <your FairValid API key>. If Request headers is absent, use OAuth or the Claude Code instructions below. The API key is not an OAuth client secret.

  1. 打开“自定义”→“连接器”→“添加自定义连接器”。对于托管组织，由所有者或符合条件的企业角色从“组织设置”→“连接器”→“添加”→“自定义”→“Web”开始操作。
  2. 输入 FairValid 和 https://mcp.fairvalid.com/mcp。
  3. 选择“立即登录”。如果出现 OAuth 客户端选项，请选择“自动注册”。手动注册的客户端 ID 和密钥字段请留空。
  4. 在 fairvalid.com 上登录，查看所选的正式密钥及权限，然后批准连接。请在对话的连接器控制中启用 FairValid。
  5. 运行下方的只读连接检查。仅当您通过 Request headers 使用测试 API 密钥连接时，才需执行沙盒检查。

官方文档：Anthropic：自定义连接器与身份验证 · Anthropic：远程连接器可用性

Claude Code

Claude Code 支持通过 API 密钥直接连接。请在启动 Claude Code 的环境中设置 FAIRVALID_API_KEY，首次验证时请使用测试密钥。请勿将实际密钥写入项目文件。

  1. 将以下配置合并到项目的 .mcp.json 中，并保留已有的服务器。文件中应填写字面形式的环境变量引用，而不是密钥值本身。
  2. 在可使用 FAIRVALID_API_KEY 的环境中启动 Claude Code。如有提示，请批准项目的 MCP 配置。
  3. 运行 claude mcp list，然后在会话中查看 /mcp。确认 FairValid 已连接并提供六个工具，然后执行下方的沙盒检查。
{
  "mcpServers": {
    "fairvalid": {
      "type": "http",
      "url": "https://mcp.fairvalid.com/mcp",
      "headers": {
        "Authorization": "Bearer ${FAIRVALID_API_KEY}"
      }
    }
  }
}

官方文档：Anthropic：Claude Code MCP 配置

Hermes Agent

以下说明适用于 NousResearch Hermes Agent。其远程 HTTP 传输支持 bearer 请求头。CLI 会将密钥以 MCP_FAIRVALID_API_KEY 存储在当前配置文件的 .env 中，并在 config.yaml 中保留一个环境变量引用。

  1. 运行下方的 add 命令。当询问是否需要身份验证时，请回答 yes，然后在隐藏输入的 API key / Bearer token 提示中输入测试 API 密钥。
  2. 请查看已发现的工具，并启用您需要的 FairValid 工具。设置必须成功连接；出错后保存已停用的连接不算设置成功。
  3. 运行 hermes mcp test fairvalid，然后启动新会话或运行 /reload-mcp。执行下方的沙盒检查。Hermes 可能会在工具名称前添加其服务器名称前缀。
hermes mcp add fairvalid \
  --url https://mcp.fairvalid.com/mcp \
  --auth header

hermes mcp test fairvalid

官方文档：NousResearch：MCP 配置 · NousResearch：MCP 连接检查 · NousResearch：标头认证 CLI 实现

Grok Bot 和 Grok

Grok Bot 和 Grok.com 的设置入口不同。在个人 Grok Bot 中，可使用下方的请求让 Bot 添加 FairValid。即使信息面板仅显示“Details”“Library”和“Computer”而没有“Setup”部分，此方法同样适用。

此外，Team Bot 还会向 Bot 的所有者或管理员开放“信息面板 → Setup → Plugins”。该设置界面需要在桌面应用中拥有 Team Bot 访问权限。使用 OAuth 时，每位团队成员都需使用自己的账户登录。

Grok.com 请前往 grok.com/connectors → New Connector → Custom。输入 https://mcp.fairvalid.com/mcp 并完成身份验证。Business 和 Enterprise 团队可能需要先由管理员配置该连接器。此连接与 Grok Bot 插件相互独立。

使用 xAI API 构建的机器人也需单独处理：其开发者需在服务器代码中配置远程 MCP 请求头。本说明并不表示 Grok Bot 提供通用的 Authorization 请求头字段。

  1. 请让您的 Bot 使用以下请求添加自定义远程 HTTPS MCP 连接。对于 Team Bot，其所有者或管理员也可以通过“设置 → 插件”进行添加。
  2. When the Bot shows the FairValid authorization card, select Authorize to open OAuth sign-in. Keep API keys out of the request and any server command.
  3. 请在 fairvalid.com 上完成 FairValid 授权同意。如有需要，每位团队成员需各自连接自己的账户。
  4. 让 Bot 列出 FairValid 的工具，并运行下方的只读连接检查。仅发现工具并不能证明验证已完成。
Add FairValid as a custom Remote HTTPS MCP server at
https://mcp.fairvalid.com/mcp using OAuth.
Show me the sign-in flow, then list its tools.
Do not submit any email verification yet.

官方文档：xAI：Grok Bot 插件和远程 HTTPS · xAI：Grok.com 自定义连接器 · xAI：面向 API 开发者的远程 MCP

Codex

在 Codex 中使用直接 API 密钥连接。在 Codex 进程可访问的环境中设置 FAIRVALID_API_KEY，首次检查请使用 Test 密钥。独立启动的桌面应用可能不会继承终端的环境变量。

  1. 运行下方命令以注册远程 Streamable HTTP 服务器。该命令仅存储环境变量的名称，而不是 API 密钥。
  2. 运行 codex mcp list，并启动新的 Codex 会话以加载该连接。确认 FairValid 出现在会话的 MCP 工具中。
  3. 如果使用 Codex 应用，请确保该变量对其执行主机可用，并视需要重启应用或开启新会话。请勿默认 CLI 设置成功后，已在运行的应用环境也会随之更新。
  4. 请确认已发现的六个工具，并完成下方的沙盒检查。
codex mcp add fairvalid \
  --url https://mcp.fairvalid.com/mcp \
  --bearer-token-env-var FAIRVALID_API_KEY

codex mcp list

官方文档：OpenAI：Codex MCP 配置

提交任务前请先检查连接

请确认已发现下方列出的全部六个工具。客户端可能会为工具名称添加自己的前缀。发现工具仅表示连接成功，并不代表验证成功。

使用 OAuth 或正式 API 密钥时，请授予余额权限，并先让智能体在不带参数的情况下调用 fairvalid_get_balance。读取余额不会消耗验证额度。请勿通过正式连接提交沙盒示例。

使用 Test API 密钥时，请改为按照下方的沙盒检查操作。正式验证可能会预留并消耗点数；请选择您有权检查的地址，并明确请求提交。

如果连接失败，请检查账户的连接器权限、端点、缺失的环境变量，以及密钥或授权是否已被撤销。如遇权限或支出上限错误，请在重试前检查已授予的权限范围或上限；更换新的幂等键并不能解决根本原因。

先进行一次免费的沙盒验证

使用 fv_test_ 密钥，并按下方示例调用 fairvalid_verify_email。测试密钥的单地址检查会直接返回模拟结果，不调用服务提供商，不创建正式验证，也不消耗额度。

其他保留示例为 undeliverable@example.com、risky@example.com、unknown@example.com、pending@example.com 和 error@example.com。pending 和 error 是有意设计的模拟，并非真实的邮箱检查。单地址 pending 示例没有可轮询的任务。

{
  "email": "deliverable@example.com",
  "idempotency_key": "agent-demo-2026-10-23"
}

工具与权限

fairvalid_verify_email 接收 email 和 idempotency_key。fairvalid_submit_job 接收 emails、idempotency_key 以及可选的 name，支持 1 至 5,000 个地址。在 live 模式下提交需要 submit 权限范围。

fairvalid_get_job 接收 job_id 以读取状态。fairvalid_get_results 接收 job_id 以及可选的 cursor、filter 和 search，每次最多读取 50 条结果。在 live 模式下读取需要 read 权限范围。

fairvalid_cancel_job 接收 job_id 并请求取消；正在进行的验证可能仍会完成。取消正式任务需要 submit 权限范围。fairvalid_get_balance 不接收参数，需要具有 balance 权限范围的正式密钥。测试密钥无法读取正式额度余额。

密钥决定所属工作区。工具不接受 API 密钥或工作区参数。权限范围检查、撤销、消费上限和工作区额度规则对 MCP 的适用方式与客户 API 完全相同。

实时跟踪任务直至获得结果

使用 OAuth 或 fv_live_ 密钥时，单个验证和批量验证都会提交异步任务。返回 accepted 响应和 job_id 表示任务已被接收，并不代表邮箱检查已完成。处理时间取决于队列和验证服务提供商。

如需在沙盒中演练任务流程，请使用保留的示例地址调用 fairvalid_submit_job。沙盒任务支持状态查询、结果、取消和重放，不会调用服务商，也不消耗额度。

  1. 使用稳定的 idempotency_key 仅提交一次，并保存返回的 job_id。
  2. 使用该 job_id 调用 fairvalid_get_job。请拉开轮询请求的间隔，并在出现临时故障时进行退避。
  3. 使用相同的 job_id 调用 fairvalid_get_results。将每个 next_cursor 作为 cursor 传回，直到 next_cursor 为 null。游标会保留原始的筛选条件和搜索内容。
  4. 请同时检查任务状态和每条结果。未知、全收和仍在验证中的结果均不能证明邮箱有效。

重试时不会产生重复任务

两种提交工具都需要提供 idempotency_key，长度为 8 到 128 个字符，可包含字母、数字、点、冒号、下划线或连字符。若响应结果不确定，请使用相同的 API 密钥或 OAuth 连接、相同的 idempotency_key 以及未更改的输入进行重试。重放范围限定于底层 API 密钥：轮换 OAuth 访问令牌会保留该身份，但选择其他 API 密钥并重新提交可能会创建新的运行。使用已有幂等键但任务内容已更改的请求将被拒绝。仅在有意发起新的运行时才使用新的幂等键。

读取结果前，请先检查 isError。到达客户 API 的调用会在 structuredContent 中包含其响应和 HTTP 状态码；参数校验错误可能仅返回文本内容。请检查 API 错误的 code，并遵循任何重试提示。超时或临时错误并不能证明原始提交不存在。

正式密钥可以消耗工作区额度。连接自主代理前，请先设置总上限：已扣除和已预留的额度均计入其中。已完成的有效和无效验证各消耗 1 点额度；未知、未确定的全收（catch-all）结果以及技术故障最终不扣除验证额度。

仍需帮助？

登录以创建私密支持工单。

联系支持团队