How to Build a CAPTCHA Solver Tool with FastMCP

Introduction

When an authorized AI-agent workflow reaches a CAPTCHA checkpoint, developers need a bounded tool contract instead of open-ended retries. FastMCP provides native FastMCP server and @mcp.tool decorator. This repository shows that verified boundary and naturally connects CapSolver only after explicit authorization.

Related MCP server: goose-capsolver-mcp-extension

What this repository demonstrates

• a verified native FastMCP server and @mcp.tool decorator 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 FastMCP 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 FastMCP 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.