Справочник инструментов MCP
Все инструменты MCP-сервера CaptchaSonic — параметры, поддерживаемые типы капч, форматы ответов и ошибки.
Хостинг-сервер (https://mcp.captchasonic.com) и локальный пакет (@captchasonic/mcp-server) предоставляют одни и те же пять инструментов. Решения списываются с вашего API-ключа по обычным ценам API; неудачные и просроченные решения возвращаются.
Solve token CAPTCHA
solve_token_captcha
Решает токен-капчу на веб-странице и ждёт токен (обычно 5–60 секунд). Клиенты с поддержкой уведомлений о прогрессе показывают «Solving… Ns» во время решения.
| Параметр | Тип | Описание |
|---|---|---|
type | string | Один из токен-типов ниже. |
website_url | string | Полный URL страницы с капчей. |
website_key | string | Ключ сайта: data-sitekey, параметр render= или GeeTest captchaId (v4) / gt (v3). Обязателен для большинства типов. |
proxy | string | Необязательно. Решать через ваш прокси, например http://user:[email protected]:8080. Без него решение идёт без прокси. |
metadata | object | Необязательно. Доп. данные, например { "rqdata": "…" } для enterprise-страниц или { "gt": "…", "challenge": "…" } для GeeTest v3. |
task_timeout | integer | Необязательно. Сколько секунд может решать солвер, 60–120 (по умолчанию 120). |
wait_for_result | boolean | Необязательно, по умолчанию true. false сразу возвращает task_id; токен получите через get_task_result. |
type | Капча | Обязательно | Цена |
|---|---|---|---|
recaptcha_v2 | reCAPTCHA v2 (чекбокс, невидимая) | website_url, website_key | $0.0005 |
recaptcha_v3 | reCAPTCHA v3 | website_url, website_key | $0.001 |
turnstile | Cloudflare Turnstile | website_url (sitekey желателен) | $0.0005 |
cloudflare_challenge | Страница проверки Cloudflare (cf_clearance) | website_url | $0.0005 |
popularcaptcha | PopularCaptcha / hCaptcha-подобные | website_url, website_key | $0.0025 |
geetest | GeeTest v3 / v4 | website_url, website_key | $0.0005 |
mtcaptcha | MTCaptcha | website_url, website_key | $0.0005 |
Результат
{
"task_id": "9f2c4e1a7b3d5c60",
"status": "ready",
"token": "0.Zm9vYmFy…",
"user_agent": "Mozilla/5.0 …",
"cookies": { "cf_clearance": "…" }
}
Отправьте token в поле формы виджета (g-recaptcha-response, cf-turnstile-response, h-captcha-response, …). Для cloudflare_challenge установите возвращённые cookies и отправляйте запросы с тем же user_agent (и тем же прокси, если он использовался). Если пришло "status": "processing", вызовите get_task_result с task_id.
Solve image CAPTCHA
solve_image_captcha
Решает графическую или аудиокапчу и сразу возвращает ответ.
| Параметр | Тип | Описание |
|---|---|---|
type | string | Один из графических типов ниже. |
images | string[] | Изображения задания по порядку (1–50): base64, data: URL или публичные http(s) URL. До 5 МБ каждое и около 7,8 МБ на все изображения и примеры вместе. |
question | string | Текст задания точно как на экране, например Select all images with a bus. |
question_type | string | Только для popularcaptcha_image: objectClassify, objectClick, objectDrag, objectTag, grid, bbox, bboxdd. |
examples | string[] | До 3 эталонных изображений, например фрагмент слайдера. |
website_url | string | Необязательный URL страницы; улучшает некоторые солверы. |
module, numeric, case_sensitive, max_length | Параметры OCR. |
type | Капча | Обязательно | question | Ответ |
|---|---|---|---|---|
popularcaptcha_image | PopularCaptcha / hCaptcha-подобная | images, question | Текст задания; при возможности укажите question_type | Классификация: boolean на изображение. Клик: точки {x,y} на изображение. Перетаскивание: {start,end} на изображение. |
recaptcha_v2_image | Сетка reCAPTCHA v2 | images, question | Цель, например traffic lights, или код /m/ | Одно изображение сетки 3x3/4x4: индексы подходящих клеток с нуля. Отдельные клетки: boolean на клетку. |
geetest_image | GeeTest (девять клеток, клик, слайдер, match) | images, question | geetest_nine:<задание>, geetest_click:<задание>, geetest_slide (фрагмент в examples), match | Девять клеток: boolean на клетку. Клик: координаты. Слайдер: смещение [x, y]. Match: два индекса клеток. |
aws_waf_image | Сетка AWS WAF | images, question | например Choose all the chairs | Индексы подходящих клеток с нуля. |
tiktok_image | TikTok (вращение, слайдер, клик) | images, question | tiktok_whirl, tiktok_slide (оба требуют examples), tiktok_click | Ответ солвера (поворот / смещение / клики) в списке из одного элемента. |
binance_image | Binance (сетка, слайдер) | images, question | binance_grid:<цель>, binance_slide (фрагмент в examples) | Сетка: подходящие клетки. Слайдер: смещение [x, y]. |
tencent_image | Tencent (сетка, клик, слайдер) | images | tencent_grid:<цель>, tencent_click (нужны examples), tencent_slide (по умолчанию) | Сетка/клик: {sol: [[x, y]…], size}. Слайдер: [x, y] и size. |
prosopo_image | Prosopo / Procaptcha | images, question | Текст задания | Подходящие клетки. |
slide_image | Обычный слайдер | images | — | Смещение [x, y]. Сначала фон, затем фрагмент (или в examples). |
ocr | Текст на изображении | images | — | Одна строка на изображение. |
mtcaptcha_image | Текст MTCaptcha | images | — | Одна строка на изображение. |
audio | Аудиокапча | images (аудиофайл) | — | Распознанный текст. |
Каждый результат содержит answer_format — описание того, как применить answers.
Get task result
get_task_result
| Параметр | Тип | Описание |
|---|---|---|
task_id | string | task_id из solve_token_captcha. |
Возвращает ту же структуру, что и solve_token_captcha. Результаты хранятся несколько минут после готовности.
Get balance
get_balance
Без параметров. Возвращает balance_usd и активный plan с лимитами.
List CAPTCHA types
list_captcha_types
Без параметров. На локальном сервере работает без API-ключа (для подключения к хостинг-серверу ключ нужен). Возвращает все поддерживаемые типы с обязательными полями, форматом ответа и ценой. Агенты вызывают его, если не уверены, какой тип выбрать.
Errors
Ошибки возвращаются как ошибки инструмента с кодом и подсказкой, например:
ERROR_ZERO_BALANCE: CaptchaSonic API error 10
The account has no balance. Top up at https://my.captchasonic.com.
| Код | Значение |
|---|---|
ERROR_KEY_DOES_NOT_EXIST | API-ключ отсутствует, неверен или отозван. |
ERROR_ZERO_BALANCE | Пополните баланс. |
ERROR_CAPTCHA_UNSOLVABLE | Не удалось решить; загрузите новое задание и повторите. Средства возвращены. |
ERROR_CAPTCHA_TIMEOUT | Не решено за task_timeout. Средства возвращены. |
ERROR_MISSING_REQUIRED_FIELDS | Не хватает обязательного параметра для этого type. |
ERROR_DAILY_LIMIT_EXCEEDED, ERROR_MINUTE_LIMIT_EXCEEDED | Достигнуты лимиты тарифа. |
ERROR_SERVICE_UNAVAILABLE | Сервис занят; запрос повторяется автоматически, затем ошибка возвращается. |
Хостинг-сервер также возвращает HTTP 401, если нет заголовка Authorization, и 429, если ключ отправляет больше 120 MCP-запросов в минуту (учитываются все вызовы инструментов и установка соединения).