MCP Tools Reference

The hosted server (https://mcp.captchasonic.com) and the local package (@captchasonic/mcp-server) expose the same five tools. Solves are billed to your API key at normal API prices; failed and timed-out solves are refunded.

Solve token CAPTCHA

solve_token_captcha

Solves a token CAPTCHA on a web page and waits for the token (usually 5–60 seconds). Clients that support progress notifications see "Solving… Ns" updates while it runs.

Parameter	Type	Description
`type`	string	One of the token types below.
`website_url`	string	Full URL of the page with the CAPTCHA.
`website_key`	string	Sitekey from the page: `data-sitekey`, the `render=` parameter, or GeeTest `captchaId` (v4) / `gt` (v3). Required for most types.
`proxy`	string	Optional. Solve through your proxy, e.g. `http://user:[email protected]:8080`. Omit to solve without one.
`metadata`	object	Optional extra challenge data, e.g. `{ "rqdata": "…" }` for enterprise pages or `{ "gt": "…", "challenge": "…" }` for GeeTest v3.
`task_timeout`	integer	Optional. Seconds the solver may take, 60–120 (default 120).
`wait_for_result`	boolean	Optional, default `true`. `false` returns a `task_id` immediately; fetch the token with `get_task_result`.

`type`	CAPTCHA	Required	Price
`recaptcha_v2`	reCAPTCHA v2 (checkbox, invisible)	`website_url`, `website_key`	$0.0005
`recaptcha_v3`	reCAPTCHA v3	`website_url`, `website_key`	$0.001
`turnstile`	Cloudflare Turnstile	`website_url` (sitekey recommended)	$0.0005
`cloudflare_challenge`	Cloudflare challenge page (`cf_clearance`)	`website_url`	$0.0005
`popularcaptcha`	PopularCaptcha / hCaptcha-style	`website_url`, `website_key`	$0.0025
`geetest`	GeeTest v3 / v4	`website_url`, `website_key`	$0.0005
`mtcaptcha`	MTCaptcha	`website_url`, `website_key`	$0.0005

Result

{
  "task_id": "9f2c4e1a7b3d5c60",
  "status": "ready",
  "token": "0.Zm9vYmFy…",
  "user_agent": "Mozilla/5.0 …",
  "cookies": { "cf_clearance": "…" }
}

Submit token with the page's form field (g-recaptcha-response, cf-turnstile-response, h-captcha-response, …). For cloudflare_challenge, set the returned cookies and send requests with the same user_agent (and the same proxy, if you used one). If the result is "status": "processing", call get_task_result with the task_id.

Solve image CAPTCHA

solve_image_captcha

Solves an image or audio CAPTCHA and returns the answer immediately.

Parameter	Type	Description
`type`	string	One of the image types below.
`images`	string[]	Challenge images in order (1–50): raw base64, `data:` URLs, or public `http(s)` URLs. Max 5 MB each and about 7.8 MB for all images and examples together.
`question`	string	The prompt exactly as shown, e.g. `Select all images with a bus`.
`question_type`	string	`popularcaptcha_image` only: `objectClassify`, `objectClick`, `objectDrag`, `objectTag`, `grid`, `bbox`, `bboxdd`.
`examples`	string[]	Up to 3 reference images, e.g. the slider piece.
`website_url`	string	Optional page URL; improves some solvers.
`module`, `numeric`, `case_sensitive`, `max_length`		OCR options.

`type`	CAPTCHA	Required	`question`	Answer
`popularcaptcha_image`	PopularCaptcha / hCaptcha-style image	`images`, `question`	The prompt; set `question_type` if known	Classify: boolean per image. Click: `{x,y}` points per image. Drag: `{start,end}` per image.
`recaptcha_v2_image`	reCAPTCHA v2 grid	`images`, `question`	Target, e.g. `traffic lights`, or a `/m/` code	One 3x3/4x4 grid image: 0-based indices of matching tiles. Separate tiles: boolean per tile.
`geetest_image`	GeeTest nine-grid, click, slide, match	`images`, `question`	`geetest_nine:<prompt>`, `geetest_click:<prompt>`, `geetest_slide` (piece in `examples`), `match`	Nine: boolean per cell. Click: click coordinates. Slide: `[x, y]` offset. Match: two cell indices.
`aws_waf_image`	AWS WAF grid	`images`, `question`	e.g. `Choose all the chairs`	0-based indices of matching tiles.
`tiktok_image`	TikTok whirl, slide, click	`images`, `question`	`tiktok_whirl`, `tiktok_slide` (both need `examples`), `tiktok_click`	Solver answer (rotation / offset / clicks) in a one-element list.
`binance_image`	Binance grid, slide	`images`, `question`	`binance_grid:<target>`, `binance_slide` (piece in `examples`)	Grid: matching tiles. Slide: `[x, y]` offset.
`tencent_image`	Tencent grid, click, slide	`images`	`tencent_grid:<target>`, `tencent_click` (needs `examples`), `tencent_slide` (default)	Grid/click: `{sol: [[x, y]…], size}`. Slide: `[x, y]` with `size`.
`prosopo_image`	Prosopo / Procaptcha	`images`, `question`	The prompt	Matching grid cells.
`slide_image`	Generic slider	`images`	—	`[x, y]` offset. Background first, piece second (or in `examples`).
`ocr`	Text image	`images`	—	One string per image.
`mtcaptcha_image`	MTCaptcha text	`images`	—	One string per image.
`audio`	Audio challenge	`images` (the audio file)	—	Transcribed text.

Every result includes answer_format, a plain-language description of how to apply answers.

Get task result

get_task_result

Parameter	Type	Description
`task_id`	string	`task_id` from `solve_token_captcha`.

Returns the same shape as solve_token_captcha. Results expire a few minutes after they are ready.

ERROR_ZERO_BALANCE: CaptchaSonic API error 10
The account has no balance. Top up at https://my.captchasonic.com.

Code	Meaning
`ERROR_KEY_DOES_NOT_EXIST`	API key missing, wrong or revoked.
`ERROR_ZERO_BALANCE`	Top up your balance.
`ERROR_CAPTCHA_UNSOLVABLE`	Could not be solved; load a fresh challenge and retry. Refunded.
`ERROR_CAPTCHA_TIMEOUT`	Not solved within `task_timeout`. Refunded.
`ERROR_MISSING_REQUIRED_FIELDS`	A required parameter for this `type` is missing.
`ERROR_DAILY_LIMIT_EXCEEDED`, `ERROR_MINUTE_LIMIT_EXCEEDED`	Plan limits reached.
`ERROR_SERVICE_UNAVAILABLE`	Busy; retried automatically, then reported.

The hosted server also returns HTTP 401 when the Authorization header is missing and 429 when a key sends more than 120 MCP requests per minute (every tool call and connection setup counts).

Solve token CAPTCHA

Solve image CAPTCHA

Get task result

Get balance

List CAPTCHA types

Errors