Solve CAPTCHAs in Agno with MCP (5 Lines, 100 Free Solves)

CapSolver published an Agno integration guide that requires manual API calls, custom polling loops, and a paid account. Here is how to do it with MCP in 5 lines — with 100 free solves included.

The Problem

Agno is a Python framework for building multi-agent systems (39K+ GitHub stars). When your Agno agent navigates the web, it hits CAPTCHAs — Cloudflare Turnstile, reCAPTCHA, hCaptcha. The agent stops. The task fails.

CapSolver's approach: install their SDK, manage API keys in your code, write polling loops, handle errors manually. Your agent code becomes a CAPTCHA-solving integration project.

The MCP approach: register a server, and your agent discovers CAPTCHA solving as a tool automatically. No SDK. No polling. No integration code.

Setup: 2 Minutes

1. Get a Free API Key

Sign up at gatesolve.dev — 100 free solves, no credit card.

2. Install the MCP Server

npm install -g @gatesolve/mcp-server

3. Connect in Your Agno Agent

import asyncio
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.mcp import MCPTools

async def main():
    # Connect to GateSolve MCP server
    mcp_tools = MCPTools(
        command="npx @gatesolve/mcp-server",
        env={"GATESOLVE_API_KEY": "gs_your_key"}
    )
    await mcp_tools.connect()

    agent = Agent(
        model=OpenAIChat(id="gpt-4o"),
        tools=[mcp_tools],
        instructions=[
            "When you encounter a CAPTCHA, use solve_captcha.",
            "Extract the sitekey from the page source first."
        ],
    )

    # Agent can now solve CAPTCHAs via GateSolve
    agent.print_response(
        "Navigate to example.com/login and solve any CAPTCHAs"
    )

asyncio.run(main())

That's it. Your agent now has access to solve_captcha, detect_captcha, and check_status as native tools.

What Happens Under the Hood

// When your Agno agent hits a CAPTCHA, it calls:
{
  "tool": "solve_captcha",
  "arguments": {
    "url": "https://example.com/login",
    "type": "turnstile",
    "sitekey": "0x4AAAA..."
  }
}

// GateSolve returns:
{
  "token": "0.Abc123...",
  "solve_time_ms": 8400,
  "type": "turnstile"
}

// Agent injects token and continues — no custom code needed

The MCP protocol handles tool discovery, argument validation, and result formatting. Your agent code stays clean — it just calls tools when it needs them.

CapSolver vs GateSolve MCP

# CapSolver approach: manual API calls, custom polling
import capsolver

capsolver.api_key = "CAP-xxx"

solution = capsolver.solve({
    "type": "AntiTurnstileTaskProxyLess",
    "websiteURL": "https://example.com",
    "websiteKey": "0x4AAAA...",
})
# Requires: pip install capsolver
# Requires: CapSolver account + balance
# No free tier
# Agent must know WHEN to call this — no automatic discovery

# GateSolve MCP approach: agent discovers tools automatically
from agno.tools.mcp import MCPTools

mcp_tools = MCPTools(command="npx @gatesolve/mcp-server")
await mcp_tools.connect()

# Agent now has solve_captcha, detect_captcha, check_status
# No API key management in code
# No polling loops
# 100 free solves included
# Agent discovers capabilities via MCP protocol

Multi-Agent Teams

Agno excels at multi-agent coordination. Share the MCP connection across a team — the scraper agent solves CAPTCHAs while the analyst processes data:

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.mcp import MCPTools
from agno.team import Team

async def main():
    mcp_tools = MCPTools(command="npx @gatesolve/mcp-server")
    await mcp_tools.connect()

    # Scraper agent with CAPTCHA solving
    scraper = Agent(
        name="Scraper",
        model=OpenAIChat(id="gpt-4o"),
        tools=[mcp_tools],
        instructions=[
            "Scrape data from target URLs.",
            "If you hit a CAPTCHA, use solve_captcha to bypass it.",
        ],
    )

    # Analyst agent processes scraped data
    analyst = Agent(
        name="Analyst",
        model=OpenAIChat(id="gpt-4o"),
        instructions=["Analyze scraped data and summarize findings."],
    )

    team = Team(agents=[scraper, analyst])
    team.print_response("Scrape pricing from competitor sites")

Supported CAPTCHA Types

• Cloudflare Turnstile — 0.02 USD/solve
• reCAPTCHA v2/v3 — 0.03 USD/solve
• hCaptcha — 0.03 USD/solve

Why MCP Matters for Agno

Agno's native MCP support means tools are composable. Your agent doesn't import a CAPTCHA library — it connects to a CAPTCHA service via protocol. Swap GateSolve for another MCP-compatible solver and your agent code doesn't change. That is the point of standardized interfaces.

CapSolver's SDK is locked to their API. MCP is locked to nothing. Your agent gets tool discovery, capability negotiation, and structured results for free.