Add CAPTCHA solving to your AI agent with MCP

The official @solvethree/sdk download includes the solvethree-mcp executable. The configurations below use npx to run it from the supplied package URL. There’s no hosted MCP endpoint to enter.

• Make npx available in the environment where your MCP host runs.
• Set SOLVETHREE_API_KEY to your workspace API key in the host environment. Keep it out of browser code and prompts.
• Set SOLVETHREE_PROXY in that environment. The reCAPTCHA tool reads its single proxy from this variable, not from the tool request.

For a host that accepts JSON MCP configuration, add this server entry:

{
  "mcpServers": {
    "solvethree": {
      "command": "npx",
      "args": [
        "--yes",
        "--package=https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz",
        "solvethree-mcp"
      ]
    }
  }
}

For Codex, use this TOML configuration instead. Its env_vars entry forwards the two variables from the host environment; it doesn’t set their values.

[mcp_servers.solvethree]
command = "npx"
args = ["--yes", "--package=https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz", "solvethree-mcp"]
env_vars = ["SOLVETHREE_API_KEY", "SOLVETHREE_PROXY"]
startup_timeout_sec = 60
tool_timeout_sec = 100

Start or reload the host with those environment variables available. Check that it exposes solvethree_capabilities, solvethree_create_recaptcha, solvethree_create_kasada, solvethree_create_tmpt, and solvethree_get_task.

Before creating a reCAPTCHA task, set up the target site profile and make sure it is active for your workspace. Sending a hostname and action through MCP does not create that profile.

Use solvethree_capabilities to inspect the available capabilities. For reCAPTCHA v3 Enterprise, call solvethree_create_recaptcha with this request:

{
  "site": "accounts.example.com",
  "action": "login",
  "requestId": "agent-login-001",
  "waitMs": 0
}

Replace accounts.example.com with your target site and login with the action your application needs. Choose a requestId for this logical task and keep it with the request. With waitMs set to zero, retrieve the result separately rather than waiting for completion in this call.

Each MCP create requires a requestId, even though that field is optional in the underlying task API. Use 1–64 ASCII letters, numbers, underscores, or hyphens.

1. 1.

   Keep the returned task ID

   Task creation isn’t the result. Save the task ID so the agent can retrieve that same task.

2. 2.

   Call solvethree_get_task

   Use the task ID returned by the create call. If the status is pending or solving, retrieve the task again later. Neither status contains a usable solution.

3. 3.

   Handle the terminal status

   On ready, pass the solution to your browser or application integration. On failed, inspect errorCode and error and stop polling that task.

For reCAPTCHA, submit solution.token through your browser or application request. Set its User-Agent and sec-ch-ua headers from the returned userAgent and secChUa, and reuse the proxy configured in SOLVETHREE_PROXY. Keep that proxy session pinned if your provider rotates exits.

Kasada returns headers and Ticketmaster TMPT returns a raw cookie value. Apply the output for the task you requested; these results are not interchangeable.

The MCP server doesn’t drive a browser or fill forms. Its host receives private solution data, and your application performs the submission. Check the target’s response separately: ready means solvethree generated a solution, not that the target accepted it.

A connection timeout doesn’t prove that task creation failed. If you received a task ID, retrieve it. Otherwise, repeat the same create request with the same requestId and unchanged task inputs to recover the existing task. Don’t generate a new ID just because the response was lost.

Reusing a request ID with different task inputs conflicts. If the task itself failed, read its error before deciding what to change; blindly resubmitting invalid inputs won’t fix them. For the distinction between request errors and task failures, see CAPTCHA API errors.