AI 智能体与 MCP

CaptchaSonic 为 AI 智能体原生设计。任何智能体都可以通过我们的 MCP 服务器 来解决验证码——这是一个单一的 stdio 二进制程序，通过 Model Context Protocol 暴露三个工具（health_check、get_balance、solve_captcha）。由于 MCP 是通用标准，同一个服务器可以接入 Claude Code、Antigravity、Cursor、Windsurf 以及任何其他兼容 MCP 的客户端。如果你的智能体无法使用 MCP，也始终可以直接调用 SDK。

Golden Path for Agents

把下面的片段交给任何智能体，它就能在一次往返内解决验证码：

# Claude Code（或任意 MCP 客户端）：一次性注册服务器
claude mcp add sonic --env SONIC_API_KEY=sonic_xxx -- npx -y @captchasonic/mcp-server
# 无 MCP 时——同样的三调用生命周期，使用 curl（createTask 后替换 TASK_ID）：
curl -s https://api.captchasonic.com/createTask  -H 'content-type: application/json' -d '{"clientKey":"sonic_xxx","task":{"type":"AntiTurnstileTaskProxyLess","websiteURL":"https://example.com","websiteKey":"0x4AAAAAAA..."}}'
curl -s https://api.captchasonic.com/getTaskResult -H 'content-type: application/json' -d '{"clientKey":"sonic_xxx","taskId":"TASK_ID"}'

---

Claude Code

使用 claude mcp add 命令添加 MCP 服务器。通过环境变量传递你的 API 密钥，避免其进入源代码管理：

claude mcp add sonic --env SONIC_API_KEY=sonic_xxx -- npx -y @captchasonic/mcp-server

该命令通过 npx 运行 @captchasonic/mcp-server 包——无需单独安装。想要固定的全局安装？运行一次 npm install -g @captchasonic/mcp-server，然后改用 -- sonic-mcp 作为命令。

添加后，智能体即可使用三个工具：

• health_check —— 验证 API 服务器是否正常运行（无需 API 密钥）。
• get_balance —— 返回账户当前余额（美元）。
• solve_captcha —— 提交验证码（图片、网格、滑块、OCR、Geetest、TikTok、Binance 等）并返回类型化的解答。

Claude 技能插件（推荐）

如需技能驱动的引导式工作流，请安装官方 captchasonic-skill 插件。它捆绑了三个 Claude 技能，并附带 .mcp.json，在安装时自动配置 MCP 服务器。先添加一次市场，然后在 Claude Code 中安装插件：

/plugin marketplace add captchasonic/captchasonic-skill
/plugin install captchasonic

想用一行命令？npx skills add https://github.com/captchasonic/captchasonic-skill 可安装同一套技能。无论哪种方式，都需要注册一次 API 密钥，以便捆绑的 MCP 服务器能够鉴权：

claude mcp add sonic --env SONIC_API_KEY=sonic_xxx -- npx -y @captchasonic/mcp-server

随后这三个技能会引导智能体完成常见工作流：

• captchasonic-setup —— 首次安装并验证 MCP 服务器。
• captchasonic-solve —— 在分步指导下解决任意类型的验证码。
• captchasonic-balance —— 查询账户余额与额度状态。

---

Antigravity

Antigravity 使用标准 MCP 协议，因此在其 MCP 配置中将 CaptchaSonic 注册为通用 stdio 服务器。添加以下条目：

{
  "mcpServers": {
    "sonic": {
      "command": "npx",
      "args": ["-y", "@captchasonic/mcp-server"],
      "env": {
        "SONIC_API_KEY": "sonic_xxx"
      }
    }
  }
}

保存后，重新加载 Antigravity 的 MCP 服务器，health_check、get_balance 和 solve_captcha 工具就会出现在智能体的工具列表中。

---

Cursor

在 Cursor 中打开 Settings → MCP（或编辑 ~/.cursor/mcp.json），添加 stdio 服务器：

{
  "mcpServers": {
    "sonic": {
      "command": "npx",
      "args": ["-y", "@captchasonic/mcp-server"],
      "env": {
        "SONIC_API_KEY": "sonic_xxx"
      }
    }
  }
}

重启 Cursor 的 MCP 连接。三个 CaptchaSonic 工具现在即可被智能体调用。

---

Windsurf

在 Windsurf 中打开 Settings → Cascade → MCP Servers（或编辑 ~/.codeium/windsurf/mcp_config.json），添加相同的 stdio 配置块：

{
  "mcpServers": {
    "sonic": {
      "command": "npx",
      "args": ["-y", "@captchasonic/mcp-server"],
      "env": {
        "SONIC_API_KEY": "sonic_xxx"
      }
    }
  }
}

刷新服务器列表，CaptchaSonic 的工具便可在 Cascade 中使用。

---

Generic MCP (stdio)

任何 MCP 客户端都接受相同的原始 stdio 配置。将 command 指向二进制程序，并通过 env 传入 SONIC_API_KEY。Node 运行时现已发布；Python 运行时即将推出。

Node（@captchasonic/mcp-server）：

{
  "mcpServers": {
    "sonic": {
      "command": "npx",
      "args": ["-y", "@captchasonic/mcp-server"],
      "env": {
        "SONIC_API_KEY": "sonic_xxx"
      }
    }
  }
}

Python —— 即将推出。 通过 uvx 安装的 Python MCP 包正在开发中。目前请使用上面的 Node 运行时，或直接调用 SDK。

---

n8n

CaptchaSonic 提供了一个 n8n 社区节点。在你的 n8n 实例中进入 Settings → Community Nodes，安装 n8n-nodes-captchasonic，然后用你的 API 密钥创建 CaptchaSonic 凭证。该节点提供解题和余额查询操作，可加入任意工作流。

---

Without MCP (direct SDK)

如果你的智能体无法运行 MCP 服务器，可以直接调用 SDK。令牌类验证码只需一次函数调用。

Python：

from captchasonic import CaptchaSonic

solver = CaptchaSonic("YOUR_API_KEY")
result = solver.solve_turnstile(
    website_url="https://example.com",
    website_key="0x4AAAAAAA...",
)
print(result["token"])

Node：

import { CaptchaSonic } from "captchasonic"

const solver = new CaptchaSonic("YOUR_API_KEY")
const result = await solver.solveTurnstile({
  websiteURL: "https://example.com",
  websiteKey: "0x4AAAAAAA...",
})
console.log(result.token)

完整方法列表请参阅 Python SDK 和 Node.js SDK 页面，原始的三次调用生命周期请参阅 REST API 参考。