Add reCAPTCHA v2 Handling to Cursor with CapSolver MCP

TL;DR

• Cursor can call CapSolver through the Model Context Protocol (MCP), so an AI agent can handle reCAPTCHA v2 in an authorized browser or data workflow.
• Install capsolver-core and capsolver-mcp, add the server to Cursor, and expose your API key through an environment variable.
• Use token mode when the agent already knows the page URL and site key; use browser mode when Playwright must detect and complete the challenge on the page.
• For agents outside Cursor, capsolver-agent provides a thin tool-calling layer over the same core engine.
• Add rate limits, retries, logging, and permission checks before using CAPTCHA automation in production.

Why MCP Matters for AI Development

AI coding environments are increasingly able to plan and execute multi-step tasks, but they still need explicit tools for actions outside the model. A reCAPTCHA v2 prompt can interrupt an otherwise automated test, browser workflow, or public-data collection task. MCP addresses that gap by giving Cursor a standard way to discover and invoke external capabilities.

After the CapSolver MCP server is connected, Cursor can see tool definitions for operations such as challenge detection and solution generation. The model does not need a custom adapter for every project. It selects a tool, supplies structured arguments, and receives a structured result. For more context on how these components fit into a broader automation stack, see this overview of web-scraping tools.

Use this integration only on websites and workflows you are authorized to automate. Respect site terms, privacy requirements, and applicable laws.

Install the CapSolver MCP Server

The setup has two parts: the shared solving engine and the MCP service that exposes it to Cursor.

Install the core package from its official repository:

pip install git+https://github.com/capsolver-ai/capsolver-core.git

Then install the MCP server:

pip install git+https://github.com/capsolver-ai/capsolver-mcp.git

If your workflow needs an actual browser session, install the browser extras and Chromium:

pip install "capsolver-mcp[browser] @ git+https://github.com/capsolver-ai/capsolver-mcp.git"
playwright install chromium

The official capsolver-mcp repository is the best place to check current installation and configuration details.

Configure Cursor

Open Cursor's MCP settings and register a server with these values:

Name: capsolver
Type: stdio
Command: capsolver-mcp
Environment Variables: CAPSOLVER_API_KEY=YOUR_API_KEY

Obtain the API key from your CapSolver dashboard and keep it out of source control. If Cursor cannot resolve capsolver-mcp, specify the absolute path to the Python executable and launch the package with -m capsolver_mcp.

Once the configuration is saved and the process connects successfully, Cursor should display the tools exposed by the server, including tools such as solve_captcha and detect_captchas. At that point an agent can request a solve as part of an authorized workflow without embedding the integration logic in every prompt.

Choose Between Token Mode and Browser Mode

CapSolver MCP supports two useful patterns for reCAPTCHA v2. The right option depends on whether your agent already controls the request data or must interact with a rendered page.

Token mode with solve_captcha

Token mode is suited to API-oriented workflows. The agent sends the target page URL and the reCAPTCHA site key. The service returns a g-recaptcha-response token that the authorized application can place in its form submission.

Because this approach does not require a full browser session, it typically uses fewer local resources and is easier to incorporate into repeatable pipelines. It works well when the page structure and site key are already known. The CapSolver guide to solving reCAPTCHA v2 describes the relevant request parameters in more detail.

Browser mode with solve_on_page

Browser mode is useful when an agent operates through Playwright or another browser-driving framework. The MCP tool opens or controls the page, detects the challenge, obtains a solution, and places the result into the page. This keeps challenge detection and field handling out of the agent's higher-level task logic.

The pattern is particularly useful for browser agents and end-to-end QA flows, where the surrounding interaction already depends on a live DOM. Enterprise variants may require additional parameters; consult the relevant reCAPTCHA v2 Enterprise guide and apply the technique only in permitted environments.

Manual Handling Compared with MCP Integration

Feature	Manual handling	CapSolver MCP integration
Implementation	Custom logic for each workflow	Standard tools exposed through MCP
Scaling	Requires repeated human intervention	Can be incorporated into automated jobs
Maintenance	Page-specific code must be maintained	Solving interface is centralized
Runtime	Depends on a person being available	Designed for machine-driven workflows
Results	Vary with manual operation	Returned as structured tool output
Interface	No shared protocol	Model Context Protocol

Build Agents Outside Cursor with capsolver-agent

Cursor is not the only place where the core tools can be used. The capsolver-agent package provides a small wrapper that maps an LLM's tool call to methods in the underlying engine. This separation is helpful in LangChain, the OpenAI Agents SDK, or a custom orchestration loop: the model decides when a challenge tool is needed, while the executor remains responsible for validation and execution.

# Example of using capsolver-agent in a custom loop
from capsolver_agent.schema import create_executor
import asyncio

async def handle_challenge():
    executor = create_executor(api_key="YOUR_API_KEY")
    result = await executor.execute("solve_captcha", {
        "captcha_type": "reCaptchaV2",
        "website_url": "https://example.com",
        "website_key": "6Le-wvkSAAAAAPBMRT..."
    })

    if result.get("success"):
        print(f"Solution found: {result.get('solution').get('token')}")
    else:
        print(f"Error: {result.get('error')}")

# asyncio.run(handle_challenge())

The executor is deliberately thin. Your application should still decide which domains are allowed, protect credentials, validate tool arguments, record failures, and prevent uncontrolled retries. The capsolver-core repository contains the underlying engine used by this style of integration.

Production Practices for Responsible CAPTCHA Automation

Respect rate limits and server capacity

Throttle requests and introduce sensible delays. A solver is not permission to generate excessive traffic. Set per-domain limits, cap concurrency, and stop jobs when a site returns repeated rate-limit or access errors.

Use appropriate network infrastructure

Network reputation can affect whether a challenge appears and whether a session remains stable. Select infrastructure that matches the authorized use case and avoid rotating identities to evade a site's controls. This comparison of proxy services can help teams understand common options.

Add bounded retries and useful logs

Treat a failed solve as an expected operational event. Record the challenge type, tool result, timing, and non-sensitive error details. Use exponential backoff, limit retry counts, and escalate persistent failures to an operator instead of creating an infinite loop.

Keep dependencies and policies current

Challenge formats, browser APIs, and MCP tooling change over time. Pin versions in production, test upgrades in a controlled environment, and periodically review the permitted scope of the automation. A primer on what CAPTCHAs are can help teams understand why these controls appear.

Conclusion

Connecting CapSolver MCP to Cursor turns CAPTCHA handling into a discoverable tool rather than page-specific glue code. Install the core and MCP packages, register the stdio server, protect the API key, and choose token or browser mode based on the surrounding workflow. Developers building outside Cursor can expose the same capability through capsolver-agent.

The technical integration is only one part of a reliable system. Domain allowlists, rate limits, bounded retries, audit logs, and explicit authorization should travel with the solver from the first prototype to production.

FAQ

What does MCP add to Cursor?

MCP gives Cursor a standard interface for discovering and calling external tools. That removes the need to write a separate prompt adapter for each CapSolver operation.

Can this setup support reCAPTCHA v2 Enterprise?

The source packages support multiple reCAPTCHA variants, including Enterprise configurations when the required parameters are supplied. Confirm current parameters in the official repositories before implementation.

Is a browser always required?

No. Token mode can work with the website URL and site key. Browser mode is available when the agent must detect and complete the challenge within a rendered page.

Where does the API key come from?

Create a CapSolver account and retrieve the key from the user dashboard. Store it as a secret or environment variable rather than committing it to a repository.

Can MCP expose support for other challenge types?

The server can expose discovery tools such as get_supported_captchas for the challenge types available in the installed version. Tool discovery is a core concept in the Model Context Protocol. Cursor information is available from the official Cursor site.