Should I solve CAPTCHAs by default?

No. A CAPTCHA appearing at all is a signal that the target is not comfortable with the request — usually the egress, sometimes the pace. The durable fixes are a sticky residential identity, a slower cadence, or a captured session from a real sign-in. Solving is the last resort, not the strategy.

Sessions & HITL

Hand a CAPTCHA to the solver and continue

Solves the CAPTCHA blocking an already-open session and injects the token back into the page. Charged only when a CAPTCHA was actually solved.

Get an API key MCP setup

solve_captcha

What it is

The job: Clear the one wall that is not a code, not a login, and not a click.

The session already holds the page context, so this call takes no URL — only the sessionId of the live or paused session that is stuck. The CAPTCHA is passed to the configured solver and the resulting token is injected back into the page, after which the run continues.

Billing is refund-on-fail: five credits when solved is true, and a full refund with credits_charged: 0 when the attempt did not produce a solution. You are not charged for a solver that could not help.

It needs the solver to be configured on the server side (TWO_CAPTCHA_API_KEY). It is also only valid for an authorized session your own run created — there is no way to point it at a page you did not open.

The call

Call it exactly like this.

Copied from the tool's registration and the route handler — not paraphrased.

MCPsolve_captcha.mcp.jsonjson

// MCP tool call — server "twin-browser"
{
  "tool": "solve_captcha",
  "arguments": {
    "sessionId": "…"
  }
}

POST /api/v1/solve-captcharequest.shbash

curl -X POST https://twin-browser.com/api/v1/solve-captcha \
  -H "Authorization: Bearer $TWIN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"sessionId":"…"}'

Parameters accepted by solve_captcha
Parameter	Type	What it does
sessionId*	string	Id of the live or paused session holding the CAPTCHA-blocked page.

Returns

response.jsonjson

{ "solved": true, "type": "recaptcha-v2", "credits_charged": 5 }

// unsolved → { "solved": false, "type": null, "credits_charged": 0 }

What it costs

5 credits, only when solved

5 credits are charged only when solved is true. An unsolved attempt is refunded in full and reports credits_charged: 0 — you pay for outcomes, not attempts.

See the full rate card

Which one

When a different tool is the right call.

The honest answer is often the neighbouring tool. These are the trades.

connect_account

A CAPTCHA on a login is usually a symptom, not the problem: the site does not want an automated sign-in from that IP. Solving it once does not change that. If the wall keeps coming back, hand the sign-in to the user with connect_account and capture the session instead.

connect_account

submit_verification

Different walls. A verification code is something the user has; a CAPTCHA is something the site is testing. They pause a run the same way and are cleared differently.

submit_verification

Questions

solve_captcha, answered.

Should I solve CAPTCHAs by default?: No. A CAPTCHA appearing at all is a signal that the target is not comfortable with the request — usually the egress, sometimes the pace. The durable fixes are a sticky residential identity, a slower cadence, or a captured session from a real sign-in. Solving is the last resort, not the strategy.

Keep going

The rest of the tool set.

run_goal

Do one thing on one site, right now, and block until you know whether it worked.

submit_verification

Finish a sign-in that got as far as the second factor.

connect_account

Get logged into a site that an agent is not going to be allowed to log into.

control_run

Clear a blocker you can see on the page, when no code and no credential would have helped.

The mechanism behind it:Human-in-the-loop handoff Proxy & egress

Get an API key All tools