How to Add a CAPTCHA Solver MCP Tool to PraisonAI

Introduction

English · 简体中文 · 日本語 · Español · Português · 한국어

PraisonAI agents can call tools during an authorized workflow. When a PraisonAI agent reaches a CAPTCHA while running an authorized browser or data task, the workflow needs a clear checkpoint instead of an uncontrolled retry loop. This repository shows how to connect a bounded solver tool, validate its result, and stop for human review when the request is unsafe or incomplete. The example naturally connects CapSolver only after explicit authorization.

Related MCP server: sessemi-mcp

What this repository demonstrates

• a verified Agent(tools=MCP(...)) integration boundary;

• typed challenge input and structured output;

• one-attempt budget, 45-second default timeout, and result validation;

• fixture-first tests with no real key, target, or solver request;

• a manual-review result for denied, unsupported, exhausted, or malformed requests.

Quick start

python -m venv .venv
source .venv/bin/activate
pip install -e . pytest
pytest -q
python scripts/smoke.py

Minimal call

from captcha_solver_tool import solve_checkpoint

result = solve_checkpoint({
    "task_id": "authorized-qa-42",
    "origin": "https://example.test",
    "challenge_type": "recaptcha_v2",
    "authorized": True,
})
print(result["status"])

See src/captcha_solver_tool/adapter.py for the PraisonAI boundary. Production code should implement a transport using the official CapSolver API overview, createTask, and getTaskResult contracts.

Control flow

1. Detect a supported verification checkpoint.

2. Confirm the target and purpose are authorized.

3. Spend at most one solving attempt.

4. Validate a ready result before continuing.

5. Stop for a person on any error, timeout, denial, or ambiguity.

Responsible use

Use this example only with public data, systems you own, or targets where you have explicit permission. Respect site terms, rate limits, privacy obligations, and data-retention rules. Do not use it for account creation at scale, access controls, private data, credential collection, or avoiding platform safeguards.

Project status

The adapter contract and offline behavior are tested. No live PraisonAI model session and no real CapSolver request are performed by the test suite. This is an independent educational example and does not imply an official partnership.

Conclusion

The example keeps authorization, attempt budgets, result validation, and human stopping explicit. Use the official CapSolver documentation when replacing the fixture transport.

Disclosure

Developer sharing CapSolver integration examples.

License

MIT. See LICENSE.