本页面是写给 AI 智能体的。把本页（或[markdown 版本](/zh/docs/mcp/for-agents.md)）交给您的智能体，它就能自行完成配置并求解验证码，无需额外说明。

## Connect

1. 向用户索取 CaptchaSonic API 密钥（以 `sonic_` 开头）。用户可在 https://my.captchasonic.com 获取。切勿编造密钥或使用其他来源的密钥。
2. 使用 Streamable HTTP 传输添加托管服务器：
   - URL：`https://mcp.captchasonic.com`
   - 请求头：`Authorization: Bearer <密钥>`
3. 如果您的运行环境提供 CLI，请优先使用。Claude Code：

```bash
claude mcp add --transport http captchasonic https://mcp.captchasonic.com --header "Authorization: Bearer sonic_xxx"
```

4. 如果运行环境只支持本地（stdio）服务器，请设置环境变量 `SONIC_API_KEY` 为该密钥，并运行 `npx -y @captchasonic/mcp-server`。
5. 调用 `get_balance` 进行验证。返回数字表示已连接；返回 `ERROR_KEY_DOES_NOT_EXIST` 表示密钥错误。

## Decide which tool

- 页面上有生成隐藏令牌的验证码组件（reCAPTCHA、Turnstile、hCaptcha 类、GeeTest、MTCaptcha），或出现 Cloudflare “正在检查您的浏览器” 页面 → `solve_token_captcha`。
- 您看到的是视觉谜题（选图片、拖动滑块、识别扭曲文字、听音频）→ `solve_image_captcha`。
- 不确定 → 调用 `list_captcha_types`。

## Solve a token CAPTCHA

1. 在页面中找到 sitekey：
   - reCAPTCHA：`.g-recaptcha` 上的 `data-sitekey`，或 `recaptcha/api.js` 脚本 URL 中的 `render=`。如果页面调用 `grecaptcha.execute`，则为 v3。
   - Turnstile：`.cf-turnstile` 上的 `data-sitekey`（以 `0x4` 开头）。
   - hCaptcha 类：`.h-captcha` 上的 `data-sitekey`。
   - GeeTest v4：`initGeetest4` 调用中的 `captchaId`。
2. 使用 `type`、`website_url`（页面 URL）和 `website_key` 调用 `solve_token_captcha`。
3. 将返回的 `token` 填入组件使用的表单字段——`g-recaptcha-response`、`cf-turnstile-response` 或 `h-captcha-response`——然后提交表单或调用页面的回调函数。
4. 对于 `cloudflare_challenge`，设置返回的 `cookies`，并在后续请求中使用返回的 `user_agent`。
5. 如果工具返回 `"status": "processing"`，请等待几秒后用 `task_id` 调用 `get_task_result`。

令牌约两分钟后失效。请在提交前一刻再求解。

## Solve an image CAPTCHA

1. 按屏幕上的顺序分别截取每张题目图片。只裁剪图片本身，不要发送整个页面。
2. 准确复制题目文字（例如 `Select all images with a bus`）。
3. 使用 `type`、`images` 和 `question` 调用 `solve_image_captcha`。滑块题请把拼图块放在 `examples` 中。
4. 按结果中 `answer_format` 的说明使用 `answers`：点击返回的格子索引、按返回的偏移拖动，或输入返回的文字。

## Handle errors

- `ERROR_CAPTCHA_UNSOLVABLE` 或 `ERROR_CAPTCHA_TIMEOUT`：重新加载验证码后再试一次。不会扣费。
- `ERROR_ZERO_BALANCE`：停止操作，提醒用户在 https://my.captchasonic.com 充值。
- `ERROR_MISSING_REQUIRED_FIELDS`：补充消息中提到的缺失参数。
- 不要无限重试。同一页面失败两次后，向用户报告。

仅在用户有权自动化的网站上求解验证码。