NEX CAPTCHA / MCP

让 AI 助手接入验证码服务

通过托管 MCP 连接你的 AI 工具。使用现有 API Key，查阅产品、创建验证码任务并获取结果，无需部署本地服务。

连接 MCP 登录获取 API Key

选择接入流程

优先使用与实际挑战匹配的原生验证码产品，不默认使用通用 GRID。先确认产品及版本并读取模型和指引；目标允许时选 HTTP_SUBMIT，否则在浏览器支持回填原生结果时选 BROWSER_RESULT。页面出现图片网格不代表产品就是 GRID。取得真实参数；缺少参数时报告阻塞，不能猜测。
按目标集成使用原生结果：回填规定的 Token 响应字段或回调；产品返回挑战标识与证明或答案字段时，按契约成组替换或提交。保持目标会话及绑定条件，不混用新旧挑战字段，不仅替换图片，也不假设识别服务能生成任意可移植的验证码与答案。
GRID 仅作为备选：没有可用的匹配原生产品或接入方式，或经排查确认原生方案不适用于当前挑战时，才考虑使用。先检查参数、会话绑定及有效期；HTTP 403、超时或参数错误本身不能作为切换依据。仍须取得真实的当前网格图片、原始题目及浏览器交互能力；条件不足时停止并报告阻塞。
GRID 的取图、识别排队与处理、轮询及浏览器点击会增加端到端耗时；动态换图和多轮挑战还会增加操作。耗时可能超过目标挑战的有效期，不宜作为时效敏感流程的默认方案，不保证固定识别时长或目标接受结果。临近识别时再取图，应用前再次检查新鲜度；挑战过期或图片变化后丢弃旧答案，不复用过期答案或自动创建新付费任务。
使用目标网站发出的挑战及接入参数。识别服务不提供可任意转移的验证码与答案；替换控件或图片不会替换服务端挑战。
MCP 同一次创建重试须复用 requestId 和完全相同的参数。挑战变化属于新任务，需新 requestId 并再次计费。按 nextPollAfterSeconds 查询，不要用创建任务代替轮询。REST 创建请求体没有 requestId 字段。
示例使用占位值，不是可直接运行的挑战。已说明结果字段不代表目标验证已通过，也不代表完成了实时可用性测试。不要提交未支持的字段。
SUCCEEDED 仅表示已取得识别结果；还需分别确认目标网站接受验证、目标业务操作成功。识别服务无法观察这两个结果。
hCaptcha 使用已启用的原生 HCAPTCHA，再读取参数模型；当前目录中不存在时报告未开放。不要因为看到复选框或图片网格就替换成 RECAPTCHA_V2、IMPERVA、CUSTOM 或 GRID；付费前核对原生契约是否覆盖目标所需上下文。

HTTP_SUBMIT

纯 HTTP 提交

目标业务及验证提交能通过 HTTP 完成，且能保持必要会话条件。有识别 API 不代表整个网站支持纯 HTTP 操作。

获取目标挑战与参数 → 创建并查询对应识别任务 → 随目标请求提交结果 → 检查验证及业务结果。

BROWSER_RESULT

浏览器应用识别结果

浏览器工具能读取当前接入参数，并按目标集成方式使用该产品结果。浏览器执行能力与识别服务能力需要分别判断。

读取当前原生产品参数 → 识别 → 回填规定的 Token 字段或回调，或按契约成组替换或提交匹配的挑战标识与证明或答案 → 正常提交 → 检查目标验证及业务结果。仅替换图片不等于完成接入。

BROWSER_INTERACTION

浏览器图片交互

当前挑战符合所选图片产品，浏览器工具可以取得正确图片，并执行所需点击、旋转或拖动。

取得当前挑战及原始题目 → 识别 → 将答案映射到当前图片 → 执行交互 → 检查换图或下一轮挑战 → 确认目标结果。

识别成功 → 目标验证通过 → 业务完成

失败处理

失败编码	下一步
`INVALID_INPUT`	`READ_PRODUCT_SCHEMA` 补齐或修正参数；不要原样重试错误参数或切换 GRID。
`TRANSPORT_OR_WAF`	`INSPECT_REQUEST_CHAIN` 检查 HTTP、网络及 WAF 响应。403 不是识别结果；不确定是否送达时，用相同 requestId 和参数重试。
`TASK_EXPIRED`	`RECAPTURE_CHALLENGE` 检查当前挑战及有效期，确认仍有需要后再创建新付费任务。
`PROVIDER_INPUT_INVALID`	`READ_PRODUCT_SCHEMA` 上游拒绝参数，检查产品选择、当前参数及题目。
`PROVIDER_UNSOLVABLE`	`INSPECT_CHALLENGE` 先检查图片质量、题目及挑战是否仍有效，再决定是否付费重试。
`PROVIDER_UNAVAILABLE`	`RETRY_LATER` 服务可用性问题，不要仅因此更换验证码产品。
`TASK_FAILED`	`INSPECT_CHALLENGE` 暂无明确公开原因。报告任务 ID 并检查上下文；不能宣称目标拒绝或推断产品不支持。
`TARGET_REJECTED`	`CHECK_BINDING_AND_EXPIRY` 由调用方观察，不能从识别状态推断。检查目标响应、挑战关联及有效期。
`BROWSER_APPLICATION_UNSUPPORTED`	`CHANGE_EXECUTION_ENVIRONMENT` 浏览器无法使用结果，应报告执行能力限制，不能判定识别产品不可用。

01 / CONNECT

连接 MCP

托管服务

选择客户端，复制配置并替换为你的 API Key。请妥善保存配置，避免公开分享密钥。

服务地址https://app.nexcaptcha.net/mcp

API Key

在个人配置中获取 API Key，或登录后自动填入。

已有配置时，只合并 nex-captcha 节点，保留其他服务器和设置。~ 表示用户主目录，Windows 可使用 %USERPROFILE%。

Claude Code

官方配置说明

在已安装 Claude Code 的终端执行以下命令，将服务器添加到当前用户配置。

claude mcp add --transport http --scope user nex-captcha 'https://app.nexcaptcha.net/mcp' --header 'Authorization: Bearer YOUR_API_KEY'

连接检查
执行 claude mcp list 确认配置，然后在 Claude Code 内输入 /mcp 检查 nex-captcha 的连接和五个工具。
```
查询我的 Nex Captcha 余额和支持的产品列表。不要创建任务。
```

Claude Desktop

官方配置说明

打开 Claude Desktop 的 Customize → Connectors，点击 + Add → Add custom connector，名称填写 Nex Captcha，远程地址填写下方 URL。

URLhttps://app.nexcaptcha.net/mcp
在认证选项中选择 No sign in，在 Request headers 添加以下名称和值，再点击 Add。鉴权通过 API Key 请求头完成。
请求头名称Authorization
请求头值Bearer YOUR_API_KEY
连接检查
在新对话中通过 + → Connectors 启用 Nex Captcha，再发送下方查询示例。
```
查询我的 Nex Captcha 余额和支持的产品列表。不要创建任务。
```

需要支持自定义远程连接器的 Claude 版本和账户套餐；团队账户可能需由组织管理员添加。

Cursor

官方配置说明

将以下 JSON 合并到用户配置 ~/.cursor/mcp.json，或项目配置 .cursor/mcp.json。

{
  "mcpServers" : {
    "nex-captcha" : {
      "url" : "https://app.nexcaptcha.net/mcp",
      "headers" : {
        "Authorization" : "Bearer YOUR_API_KEY"
      }
    }
  }
}

连接检查
在 Cursor 设置的 MCP 服务器列表启用 nex-captcha，确认五个工具可用，再在 Agent 对话发送下方查询示例。
```
查询我的 Nex Captcha 余额和支持的产品列表。不要创建任务。
```

Codex

官方配置说明

将以下 TOML 添加到 ~/.codex/config.toml。如果已有 [mcp_servers.nex-captcha]，请替换该节点，不要重复添加。
```
[mcp_servers.nex-captcha]
url = "https://app.nexcaptcha.net/mcp"
http_headers = { Authorization = "Bearer YOUR_API_KEY" }
```
连接检查
保存后重新打开 Codex 会话。可执行 codex mcp list 查看配置，在 CLI 中用 /mcp 检查工具，再发送下方查询示例。
```
查询我的 Nex Captcha 余额和支持的产品列表。不要创建任务。
```

VS Code

官方配置说明

将以下 JSON 保存到项目的 .vscode/mcp.json；也可通过命令面板 MCP: Open User Configuration 添加到用户配置。
```
{"servers":{"nex-captcha":{"type":"http","headers":{"Authorization":"Bearer YOUR_API_KEY"},"url":"https://app.nexcaptcha.net/mcp"}}}
```
连接检查
通过 MCP: List Servers 启动 nex-captcha。在 Copilot Chat 的 Agent 模式启用其工具，然后发送下方查询示例。
```
查询我的 Nex Captcha 余额和支持的产品列表。不要创建任务。
```

Gemini CLI

官方配置说明

将以下 JSON 合并到 ~/.gemini/settings.json，或项目的 .gemini/settings.json。httpUrl 用于 Streamable HTTP。

{
  "mcpServers" : {
    "nex-captcha" : {
      "httpUrl" : "https://app.nexcaptcha.net/mcp",
      "headers" : {
        "Authorization" : "Bearer YOUR_API_KEY"
      },
      "timeout" : 30000
    }
  }
}

连接检查
重新启动 Gemini CLI，在 /mcp 中检查 nex-captcha 的连接和工具，再发送下方查询示例。
```
查询我的 Nex Captcha 余额和支持的产品列表。不要创建任务。
```

其他客户端

在支持 Streamable HTTP 的客户端中填入下方地址和请求头，然后初始化连接并调用 tools/list。
```
URL: https://app.nexcaptcha.net/mcp
Transport: Streamable HTTP
Authorization: Bearer YOUR_API_KEY
```
连接检查
先调用 get_balance 或 list_products 检查连接；需要任务结果时，向 get_task 传入 create_task 返回的 id。

验证连接

仅读取余额，不创建任务，不产生费用。

02 / TOOLS

可用工具

5 TOOLS

list_products免费

查看已启用的产品、单次美元价格及超时时间。一次返回完整列表。

get_product_schema免费

传入 productCode 获取产品的参数模型和示例，创建任务前先查阅。

create_task按产品计费

传入 productCode、adapter 和唯一 requestId 创建任务。重试时保持相同 requestId 和参数。

get_task免费

按 create_task 返回的平台 id 兜底查询结果；可使用 WebSocket 时，优先接收 task.updated。

get_balance免费

查看账户当前美元余额。1 USD = 1 balance。

仅创建任务按产品单次价格扣费，其他工具免费。任务失败或过期会退款，资产记录中可查阅计费和退款。

03 / REALTIME

WebSocket 结果推送

客户端或 MCP 宿主支持 WebSocket 时优先使用：先建立连接并等待 socket.ready，再创建任务。收到 task.updated 立即处理；仅在无法连接、断线或遗漏消息时使用 REST query.cgi 或 MCP get_task 兜底。

任务 WebSocket 独立于 MCP 的 HTTP 传输。宿主或配套进程能设置 WebSocket 握手请求头时，用同一个 API Key 放入 apiKey 请求头连接。支持 MCP 不代表具备 WebSocket 能力；无法建立连接时，用返回的 id 调用 get_task，并遵守 nextPollAfterSeconds。工具结果中的 resultDelivery 提供优先接入地址和心跳配置。

wss://app.nexcaptcha.net/socket/task.cgi

apiKey: YOUR_API_KEY
socket.ready → create_task → task.updated
task.taskId = create_task id
{"type":"heartbeat"} → {"type":"heartbeat.ack"}

WebSocket 的 API Key 只能放在握手请求头中，不能放入 URL 参数。独立客户端使用 apiKey 请求头；浏览器使用登录 Cookie，只有 API Key 时通过带请求头的 REST 查询获取结果，因为原生 WebSocket 无法设置自定义头。推送只属于当前鉴权用户。

HTTPS 环境使用 WSS。断线后退避重连；连接会回放最近 20 条终态任务，不提供完整事件历史。遗漏的 taskId 用 query.cgi 或 get_task 恢复。凭证缺失、无效、撤销或过期时以 4003 关闭；空闲或不可靠连接以 4500 关闭。

API、MCP 等入口创建的任务，每次状态变更提交成功后都会推送给该鉴权账户。成功时读取 result，失败时读取 failure.code 和 nextAction。每 20 秒发送心跳并确认 heartbeat.ack；超过 35 秒无心跳后，由每 10 秒运行的检查断开连接。断线后退避重连，不要因断线重建收费任务。按 taskId 幂等处理，已收到终态后忽略更旧或回放的消息。

容器按用户 ID 绑定每个实例上的当前单条连接；新连接以 4009 替换旧连接。同账户的多个接入者应由宿主共享订阅，被替换端应停止自动重连。实例最多 256 条连接；收到 1013 时请退避重试。慢客户端积压超过 64 条消息或 256 KiB UTF-8 数据时，以 4500 断开，遗漏的 taskId 请通过查询恢复。单条消息上限为 256 KiB。

API文档 · Python · Java 21

04 / WORKFLOW

从创建到结果

选择产品并确认参数list_products → get_product_schema
创建一次任务socket.ready → create_task(productCode, adapter, requestId)
优先接收推送结果，主动查询仅作兜底task.updated → get_task({"id": "TASK_ID"})

重试创建时复用相同 requestId 和参数。优先通过 WebSocket 获取结果；无法接入或断线时，用 id 调用 get_task 恢复结果，不要再次创建收费任务。主动查询时遵守 nextPollAfterSeconds。

支持 Streamable HTTP，协议版本 2025-03-26、2025-06-18 和 2025-11-25。使用 Authorization: Bearer API_KEY 鉴权。

让 AI 助手接入验证码服务

选择接入流程

纯 HTTP 提交

浏览器应用识别结果

浏览器图片交互

连接 MCP

Claude Code

连接检查

Claude Desktop

连接检查

Cursor

连接检查

Codex

连接检查

VS Code

连接检查

Gemini CLI

连接检查

其他客户端

连接检查

验证连接

可用工具

WebSocket 结果推送

从创建到结果