Skip to content

MCP for AI Agents

Instructions for AI agents — connect to the CaptchaSonic MCP server, pick the right tool, find the sitekey, and submit the token or answer.

This page is written for AI agents. Point your agent at it (or at the markdown version) 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:
claude mcp add --transport http captchasonic https://mcp.captchasonic.com --header "Authorization: Bearer sonic_xxx"
  1. 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.
  2. 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.