Skip to main content
Are you experiencing issues obtaining the token?
Contact support

MCP

Model Context Protocol (MCP) allows AI agents to connect to external tools and services.

CapMonster Cloud MCP provides the agent with tools for working with CAPTCHA.

How CapMonster Cloud MCP works

With MCP, an AI agent can identify the CAPTCHA type and task parameters, access CapMonster Cloud documentation, create tasks, and retrieve solution results. The agent’s ultimate goal is not only to solve the CAPTCHA, but also to correctly integrate this process into the user’s project.

To work with a web page, CapMonster Cloud MCP can be used together with the browser MCP capmonster-mcp-patchright:

AI agent
├── capmonster → CapMonster Cloud API
└── patchright → browser

capmonster handles interaction with CapMonster Cloud. patchright opens the page, helps identify the CAPTCHA type and retrieve its parameters, and applies the completed solution. The agent then transfers the verified workflow into the project code.

The typical workflow covered by SKILL.md:

  1. Get the target page URL.

  2. Identify the CAPTCHA type.

  3. Review the documentation and determine the required parameters.

  4. Retrieve the parameters from the page.

  5. Send a request to CapMonster Cloud.

  6. Retrieve the result.

  7. Apply the result on the page and integrate this workflow into the user’s code.

Note

Use automation only on resources where you are authorized to do so, such as your own website, a test environment, or a demo page.

Quick start​

Copy the prompt for your AI agent

Choose the prompt that matches your environment — Python / PyPI or TypeScript / npm — and click Copy prompt. Then paste it into Claude Code, Codex, or another AI agent. The agent will detect the client and operating system, configure capmonster and patchright, and verify that they work.

If automatic setup fails, configure MCP manually using the instructions.

After verification, provide the agent with the target page URL, project files, and the conditions under which the CAPTCHA appears. The agent should not only verify the solution in the browser, but also integrate the working CapMonster Cloud workflow into your code.

Permissions during setup

The agent may request permission to install dependencies, modify the MCP configuration, run commands, access the network, or control the browser. Review each request and confirm expected actions by clicking Allow or Approve.

In Codex, you can check or change the current permission mode with the /permissions command.

You do not need to resend the prompt before every task. In the current session, after SKILL.md has been loaded, you can provide new URLs, CAPTCHA appearance conditions, and integration tasks.

Manual setup​

You can work with the agent through a desktop application, terminal, IDE, or code editor. For the complete workflow, we recommend connecting both servers: capmonster and patchright.

Choose how you want to work — with a CLI agent or a desktop application. Each tab contains the full setup sequence for the selected option.

Step 1. Install an AI agent


You need an AI agent or another application that supports MCP.

If the agent is already installed, make sure it starts correctly and is available in your system.

For example, for Claude Code:

claude --version

For Codex:

codex --version

If the command is not found, install the selected AI agent according to its official instructions: Claude Code or Codex.

After installation, make sure the agent starts correctly and supports local MCP servers.

Agent not found after installation

If the terminal or IDE cannot find the installed agent, fully close and reopen the terminal and development environment. Applications that were already running may still use the old PATH value and may not detect the new command until restarted.

Step 2. Install Node.js and, if needed, uv


Running the MCP servers requires npx and, depending on the selected CapMonster MCP implementation, uvx.

Node.js and npx

Important:

patchright runs through npx, so Node.js is required regardless of which CapMonster MCP implementation you choose.

Check the installation:

node --version
npm --version
npx --version

If the commands are unavailable, install Node.js.

npm and npx are usually installed with Node.js, so you do not need to install npx separately.

We recommend using Node.js 18 or later.

uv and uvx

If you plan to use the Python/PyPI version of capmonster-mcp, you also need uvx.

Check whether it is available:

uvx --version

If the command is unavailable, install uv.

After installing uv, the uvx command will also become available.

Check:

uv --version
uvx --version
Note

If you use the TypeScript/npm version of capmonster-mcp, you do not need to install uv or uvx.

Step 3. Get an API key


capmonster requires a CapMonster Cloud API key.

It is passed to the MCP server through the following environment variable:

CM_API_KEY
Step 4. Choose a CapMonster MCP implementation


Two equivalent capmonster-mcp implementations are available.

This version uses the capmonster-mcp npm package and npx.

Run the MCP server with:

npx -y capmonster-mcp

You do not need to install capmonster-mcp as a dependency of your project. By default, the MCP client can run the published package directly through npx or uvx.

Installing packages with npm and pip


By default, you do not need to preinstall the MCP packages: you can run them directly through npx or uvx. If you want to install the packages in advance, use one of the options below.

CapMonster Cloud MCP

Install capmonster-mcp with npm:

npm i capmonster-mcp

You can verify the installation with:

npm list capmonster-mcp

After installation, use npx to run capmonster:

{
  "command": "npx",
  "args": ["capmonster-mcp"],
  "env": {
    "CM_API_KEY": "YOUR_API_KEY"
  }
}

Patchright MCP

If you plan to use a browser to open pages, retrieve CAPTCHA parameters, and apply solutions, install capmonster-mcp-patchright. The source code is available in the official repository:

npm i capmonster-mcp-patchright

You can verify the installation with:

npm list capmonster-mcp-patchright

Preinstalling capmonster-mcp-patchright is optional. In all examples below, you can also run it directly with:

npx -y capmonster-mcp-patchright

After installing the npm or Python package, fully restart the MCP client if the package was installed after the client had already been started.


Step 5. Configure the MCP client


Select the CLI client you use.

For a shared project configuration, create an .mcp.json file in the project root and add capmonster and patchright to it.

tip

This is not the only possible location. Claude Code supports different configuration scopes; user-specific or project-specific settings may also be stored in .claude.json or added with Claude Code commands. If an agent is configuring MCP, allow it to determine the appropriate scope and file automatically.

{
  "mcpServers": {
    "capmonster": {
      "command": "npx",
      "args": ["-y", "capmonster-mcp"],
      "env": {
        "CM_API_KEY": "YOUR_API_KEY"
      }
    },
    "patchright": {
      "command": "npx",
      "args": ["-y", "capmonster-mcp-patchright"]
    }
  }
}

After restarting Claude Code, check the connection with the /mcp command.

Replace YOUR_API_KEY with your CapMonster Cloud API key and restart the MCP client.

Step 6. Send the prompt to the agent


Open a new chat or session and send the prompt from the Quick start section. After verification, provide the page URL, project files, and the conditions under which the CAPTCHA appears.

During setup, approve only expected permission requests. You do not need to resend the prompt before every task in the current session.

Available tools​

After connecting the MCP servers, the tools become available to the AI agent automatically. You usually do not need to select them manually — the agent calls the appropriate tools based on the current task.

CapMonster Cloud​

capmonster-mcp provides the following tools:

  • get_supported_tasks — returns the supported CapMonster Cloud task types;
  • get_task_parameters(task_type) — returns the parameters for the selected task type and the solution schema;
  • get_docs(url, offset, limit, section) — loads CapMonster Cloud documentation;
  • create_task(task) — creates a task and returns taskId;
  • get_task_result(task_id) — checks the task status once;
  • get_task_result_wait(task_id, timeout_seconds, poll_interval_seconds) — automatically waits for the task to complete;
  • get_actual_user_agent() — returns the current Windows User-Agent;
  • get_balance() — returns the CapMonster Cloud account balance.

Patchright​

capmonster-mcp-patchright provides tools for browser interaction. The agent accesses them through the MCP client and selects the required actions automatically.

The current list of tools is available in the official repository and on the capmonster-mcp-patchright npm package page.

Troubleshooting​

Let the agent diagnose the issue

If the setup does not work, send the error message to the agent. It can check the runtime, startup commands, user and project MCP configurations, and suggest or apply the required fixes.

The MCP server does not start

Make sure the command from the configuration is available in the same environment where the MCP client is running:

node --version
npx --version
npx -y capmonster-mcp

If the command starts and produces no output, this is not necessarily an error: the STDIO MCP server is waiting for a client connection. You can stop the test run with Ctrl+C.

Also make sure that:

  • the JSON configuration contains no comments, trailing commas, or unclosed brackets;

  • the mcpServers, command, args, and env field names are spelled correctly;

  • the MCP client was fully restarted after the configuration was changed;

  • package downloads through npx or uvx are not blocked by the network, proxy, antivirus software, or corporate policy.

The capmonster-mcp command is not found after installing the package

A preinstalled CLI command must be available in the PATH of the process that starts the MCP client.

Check the command location:

where.exe capmonster-mcp

If the terminal can find the command but the desktop application cannot, fully close and reopen the application. If necessary, specify the full path to the executable in the command field.

capmonster or patchright tools are not displayed

Ask the agent to check where the current session loads its MCP configuration from. The location depends on the client, configuration scope, and how the server was connected:

  • in Claude Code, servers can be configured at the project or user level; the configuration may be stored in .mcp.json, .claude.json, or managed with Claude Code commands;

  • Claude Desktop uses claude_desktop_config.json;

  • Codex uses ~/.codex/config.toml, %USERPROFILE%\.codex\config.toml, or a project-level .codex/config.toml;

  • in ChatGPT Desktop, local servers can also be added through the MCP settings.

After fixing the configuration, fully restart the client and open a new session. In Claude Code, you can check the connection with /mcp; in Codex, use /mcp or codex mcp list.

get_balance returns an error

Ask the agent to check the capmonster configuration. Usually, you need to make sure that:

  • the CM_API_KEY variable contains a valid CapMonster Cloud API key;

  • the placeholder YOUR_API_KEY has been replaced;

  • the key is passed in the env block of the capmonster server, not patchright.

After changing the key, restart the MCP client. The agent can then check the connection and balance again.

If the balance is zero, top it up before creating tasks.

get_docs does not load the documentation

Ask the agent to check the MCP client’s network access to https://docs.capmonster.cloud/ and whether it can load the following file:

https://docs.capmonster.cloud/llms.txt

If the documentation is temporarily unavailable or the task parameters need additional verification, the agent can use the API specification:

https://api.capmonster.cloud/docs/swagger-ui/spec.js
patchright does not open the page

Check node, npx, and the startup command:

npx -y capmonster-mcp-patchright

If the page requires a proxy, User-Agent, or locale, provide these parameters to the agent. It can use them when launching the browser through patchright.

The task returns an error or the website rejects the solution

Provide the agent with the error message and the conditions under which the CAPTCHA appears. For diagnostics, it can:

  1. check the supported task type;

  2. retrieve the current parameters and solution schema;

  3. open the documentation for the selected CAPTCHA type;

  4. retrieve dynamic parameters again after reloading or invoking the CAPTCHA again;

  5. verify that the User-Agent, proxy, cookies, headers, and Client Hints are consistent for session-bound CAPTCHAs;

  6. make sure the result is applied in the format required for the specific CAPTCHA type.

Do not use expired challenge, token, data, blob, or other one-time parameters.

ERROR_INVALID_TASK usually indicates invalid or outdated parameters. ERROR_CAPTCHA_UNSOLVABLE may be a temporary error — the agent can verify the input data and create a new task.

Frequently asked questions​

Do I need to select and call MCP tools manually?

No. After the MCP servers are connected, the tools automatically become available to the AI agent. The agent selects and calls them based on the current task.

Do I need to connect both MCP servers?

No. You can use capmonster on its own if the CAPTCHA parameters are already known and browser interaction is not required. patchright is needed when the agent must open a page, retrieve CAPTCHA parameters, or apply the solution.

Which implementation should I choose: npm or Python?

Both capmonster-mcp implementations provide the same tools. Choose the option that matches your environment:

  • npm — if Node.js and npx are already installed;

  • Python — if you use Python 3.11 or later and have uvx installed.

patchright requires Node.js and npx in either case.

Where should I store the API key?

Pass the API key through the CM_API_KEY environment variable in the capmonster server configuration. Do not include it in the prompt, chat messages, code examples, or a public repository.

If the configuration file contains a real key, exclude it from Git or use a secure secret storage mechanism supported by the MCP client.

Do I need to send the prompt before every CAPTCHA?

No. After setup, within the current session, it is enough to provide new URLs, CAPTCHA appearance conditions, and integration tasks.

In a new session, we recommend sending the prompt again if the agent does not retain the loaded instructions and environment verification results.

How can I check which CAPTCHA types are supported?

Ask the agent to identify the supported CAPTCHA types. It can use get_supported_tasks, and for a specific task, get_task_parameters(task_type) and the documentation through get_docs.

Do I need to configure a proxy in the MCP configuration?

Not necessarily. If the browser requires a proxy, provide its parameters to the agent — it can use them when launching the browser without changing the MCP configuration.

If the selected CAPTCHA type requires your own proxy, the agent must also pass its parameters in the CapMonster Cloud task. For CAPTCHAs bound to an IP address or session, the same proxy must be used in both the browser and the task.

Was this article helpful?
Check pricing for AI CAPTCHA solver