This page is written for AI agents. Point your agent at it (or at [the markdown version](/en/docs/mcp/for-agents.md)) and it can set itself up and solve CAPTCHAs without further instructions.

## Connect

1. Ask the user for their CaptchaSonic API key (starts with `sonic_`). They get it at https://my.captchasonic.com. Never invent or reuse a key from somewhere else.
2. Add the hosted server with Streamable HTTP transport:
   - URL: `https://mcp.captchasonic.com`
   - Header: `Authorization: Bearer <key>`
3. If your harness has a CLI, prefer it. Claude Code:

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

4. If your harness only supports local (stdio) servers, run `npx -y @captchasonic/mcp-server` with the environment variable `SONIC_API_KEY` set to the key.
5. Verify by calling `get_balance`. A number means you are connected; `ERROR_KEY_DOES_NOT_EXIST` means the key is wrong.

## Decide which tool

- The page has a CAPTCHA widget that produces a hidden token (reCAPTCHA, Turnstile, hCaptcha-style, GeeTest, MTCaptcha) or a Cloudflare "checking your browser" page → `solve_token_captcha`.
- You are looking at a visual puzzle (pick images, drag a slider, read distorted text, listen to audio) → `solve_image_captcha`.
- Unsure → call `list_captcha_types`.

## Solve a token CAPTCHA

1. Find the sitekey in the page:
   - reCAPTCHA: `data-sitekey` on `.g-recaptcha`, or `render=` in the `recaptcha/api.js` script URL. v3 if the page calls `grecaptcha.execute`.
   - Turnstile: `data-sitekey` on `.cf-turnstile` (starts with `0x4`).
   - hCaptcha-style: `data-sitekey` on `.h-captcha`.
   - GeeTest v4: `captchaId` in the `initGeetest4` call.
2. Call `solve_token_captcha` with `type`, `website_url` (the page URL) and `website_key`.
3. Put the returned `token` into the form field the widget uses — `g-recaptcha-response`, `cf-turnstile-response` or `h-captcha-response` — then submit the form or call the page's callback.
4. For `cloudflare_challenge`, set the returned `cookies` and send later requests with the returned `user_agent`.
5. If the tool returns `"status": "processing"`, wait a few seconds and call `get_task_result` with the `task_id`.

Tokens expire in about two minutes. Solve right before submitting.

## Solve an image CAPTCHA

1. Capture each challenge image separately, in on-screen order. Crop to the image; don't send the whole page.
2. Copy the prompt text exactly (for example `Select all images with a bus`).
3. Call `solve_image_captcha` with `type`, `images` and `question`. Add the slider piece as `examples` for slider puzzles.
4. Apply `answers` as described in the result's `answer_format`: click the returned tile indices, drag by the returned offset, or type the returned text.

## Handle errors

- `ERROR_CAPTCHA_UNSOLVABLE` or `ERROR_CAPTCHA_TIMEOUT`: reload the challenge and try once more. You were not charged.
- `ERROR_ZERO_BALANCE`: stop and tell the user to top up at https://my.captchasonic.com.
- `ERROR_MISSING_REQUIRED_FIELDS`: add the missing parameter named in the message.
- Don't loop. After two failures on the same page, report back to the user.

Only solve CAPTCHAs on sites the user is allowed to automate.