NEX CAPTCHA / MCP

Connect your AI assistant to CAPTCHA services

Connect your AI tools to hosted MCP with your existing API Key. Discover products, create CAPTCHA tasks and retrieve results without running a local server.

Connect to MCP Sign in for your API Key

Choose an integration workflow

Prefer the product-specific (native) CAPTCHA integration over generic GRID. Identify the actual product/version and read its schema/guide before choosing. Use HTTP_SUBMIT when the target supports it, otherwise BROWSER_RESULT when the browser can apply the native result. Image grids on screen do not by themselves mean the product is GRID. Collect real inputs; missing inputs are a blocker, not permission to guess.
Apply a native result through the matching target integration: fill the expected token response field/callback, or use the returned challenge identifier and proof/answer fields together where that product requires them. Preserve the target session and bindings. Do not mix old and new challenge fields, replace only a picture, or assume the solver issues an unrelated transferable challenge/answer pair.
GRID is a fallback only when no usable matching native product/integration exists, or diagnosis confirms that the native route cannot be used for this challenge. First inspect parameters, session bindings and expiry. HTTP 403, timeout or invalid input alone is not a fallback decision. GRID still requires a real current grid image, its original instructions and browser interaction capability; if those are unavailable, stop and report the blocker.
GRID has variable end-to-end latency from image capture, solver queue/recognition, polling and browser clicks; dynamic tiles and further rounds add work. It may exceed a short-lived target challenge deadline, so it is not the default for time-sensitive flows. No fixed solve time or target acceptance is guaranteed. Capture just before solving, check freshness again before applying, and discard answers after challenge expiry or image changes. Do not reuse expired answers or automatically create another paid task.
Use the challenge and integration parameters issued by the target. A solver does not issue a freely transferable challenge/answer pair. Replacing a widget or image does not replace the server challenge.
For MCP creation, retry with the same requestId and identical parameters. A changed challenge is a new task with a new requestId and another charge. Follow nextPollAfterSeconds; do not create tasks to poll. The REST creation body does not have a requestId field.
Examples are placeholders, not runnable challenges. Documented result fields are not proof of target acceptance or a live availability test. Do not send unsupported fields.
SUCCEEDED means a solver result is available. Separately confirm that the target accepts the challenge and that the requested business operation completes. The solver cannot observe those two outcomes.
For hCaptcha use enabled native HCAPTCHA, then get its schema. If absent from the current catalogue, report unavailable. Do not substitute RECAPTCHA_V2, IMPERVA, CUSTOM or GRID based on a checkbox or image grid. Check the native contract for the required target context before paying.

HTTP_SUBMIT

HTTP submission

The target operation and challenge submission can be completed over HTTP with the same required session context. A solver HTTP API alone does not establish this.

Obtain the target challenge and parameters; create and poll the matching solver task; submit the result with the target request; inspect target validation and business outcome.

BROWSER_RESULT

Apply a result in the browser

Your browser tool can read the required current integration parameters and apply this product result through the target integration. Browser capability is separate from solver capability.

Read current native product parameters; solve; fill the expected token field/callback, or apply matching challenge identifier and proof/answer fields together as required; submit normally; inspect target validation and business outcome. Replacing an image alone is not integration.

BROWSER_INTERACTION

Browser image interaction

The current challenge matches the selected image product. Your browser tool can capture the correct image and execute the required clicks, rotation or drag actions.

Capture the current challenge and original instructions; solve; map the answer to the current image; interact; inspect for replacement images or another round; verify the target outcome.

Solver success → target acceptance → business completion

Failure handling

Failure code	Next action
`INVALID_INPUT`	`READ_PRODUCT_SCHEMA` Collect missing/correct inputs; do not retry unchanged invalid input or switch to GRID.
`TRANSPORT_OR_WAF`	`INSPECT_REQUEST_CHAIN` Inspect the HTTP/network/WAF response. A 403 is not a solver result; if delivery is uncertain, retry identical creation with the same requestId.
`TASK_EXPIRED`	`RECAPTURE_CHALLENGE` Check the current challenge and expiry. Only create a new paid task if still needed.
`PROVIDER_INPUT_INVALID`	`READ_PRODUCT_SCHEMA` The provider rejected input. Check the product, current parameters and instructions.
`PROVIDER_UNSOLVABLE`	`INSPECT_CHALLENGE` Inspect image quality/instructions and whether the challenge is current before deciding on another paid attempt.
`PROVIDER_UNAVAILABLE`	`RETRY_LATER` Service availability issue; do not change the CAPTCHA product solely for this reason.
`TASK_FAILED`	`INSPECT_CHALLENGE` No specific public cause is known. Report the task ID and inspect context; do not claim target rejection or infer an unsupported product.
`TARGET_REJECTED`	`CHECK_BINDING_AND_EXPIRY` Observed by the caller, not inferred from solver state. Check target response, challenge binding and expiry.
`BROWSER_APPLICATION_UNSUPPORTED`	`CHANGE_EXECUTION_ENVIRONMENT` The browser cannot apply the result. Report that capability limit instead of calling the solver product unavailable.

01 / CONNECT

Connect to MCP

Hosted service

Choose a client, copy its configuration and use your API Key. Keep your configuration private.

Server URLhttps://app.nexcaptcha.net/mcp

API Key

Find your API Key in account settings, or sign in to fill it automatically.

If configuration exists, merge the nex-captcha entry and preserve other servers and settings. ~ is your home directory; on Windows use %USERPROFILE%.

Claude Code

Official setup reference

Run this command in a terminal with Claude Code installed to add the server to your user configuration.

claude mcp add --transport http --scope user nex-captcha 'https://app.nexcaptcha.net/mcp' --header 'Authorization: Bearer YOUR_API_KEY'

Check the connection
Run claude mcp list, then use /mcp inside Claude Code to check nex-captcha and its five tools.
```
Show my Nex Captcha balance and supported products. Do not create a task.
```

Claude Desktop

Official setup reference

In Claude Desktop, open Customize → Connectors and add a custom connector named Nex Captcha with the URL below.

URLhttps://app.nexcaptcha.net/mcp
Select No sign in. Add the name and value below under Request headers, then add the connector. The API Key header authenticates requests.
Header nameAuthorization
Header valueBearer YOUR_API_KEY
Check the connection
Enable Nex Captcha using + → Connectors in a new conversation, then send the sample query below.
```
Show my Nex Captcha balance and supported products. Do not create a task.
```

Requires a Claude version and plan supporting custom remote connectors. A team administrator may need to add the connector.

Cursor

Official setup reference

Merge this JSON into ~/.cursor/mcp.json for your user or .cursor/mcp.json for this project.

{
  "mcpServers" : {
    "nex-captcha" : {
      "url" : "https://app.nexcaptcha.net/mcp",
      "headers" : {
        "Authorization" : "Bearer YOUR_API_KEY"
      }
    }
  }
}

Check the connection
Enable nex-captcha in the MCP server list in Cursor settings. Confirm its five tools are available, then send the sample query in Agent chat.
```
Show my Nex Captcha balance and supported products. Do not create a task.
```

Codex

Official setup reference

Add this TOML to ~/.codex/config.toml. Replace an existing [mcp_servers.nex-captcha] entry instead of adding it twice.

[mcp_servers.nex-captcha]
url = "https://app.nexcaptcha.net/mcp"
http_headers = { Authorization = "Bearer YOUR_API_KEY" }

Check the connection
Reopen your Codex session after saving. Use codex mcp list to inspect configuration and /mcp in the CLI to check tools, then send the sample query.
```
Show my Nex Captcha balance and supported products. Do not create a task.
```

VS Code

Official setup reference

Save this JSON in .vscode/mcp.json, or use MCP: Open User Configuration from the Command Palette to configure it for your user.

{"servers":{"nex-captcha":{"type":"http","headers":{"Authorization":"Bearer YOUR_API_KEY"},"url":"https://app.nexcaptcha.net/mcp"}}}

Check the connection
Start nex-captcha using MCP: List Servers. Enable its tools in Copilot Chat Agent mode and send the sample query.
```
Show my Nex Captcha balance and supported products. Do not create a task.
```

Gemini CLI

Official setup reference

Merge this JSON into ~/.gemini/settings.json or your project .gemini/settings.json. httpUrl selects Streamable HTTP.

{
  "mcpServers" : {
    "nex-captcha" : {
      "httpUrl" : "https://app.nexcaptcha.net/mcp",
      "headers" : {
        "Authorization" : "Bearer YOUR_API_KEY"
      },
      "timeout" : 30000
    }
  }
}

Check the connection
Restart Gemini CLI. Use /mcp to check nex-captcha and its tools, then send the sample query.
```
Show my Nex Captcha balance and supported products. Do not create a task.
```

Other clients

Configure this URL and header in a Streamable HTTP client, initialize the connection, then call tools/list.
```
URL: https://app.nexcaptcha.net/mcp
Transport: Streamable HTTP
Authorization: Bearer YOUR_API_KEY
```
Check the connection
Check the connection with get_balance or list_products. To retrieve a result, pass the id returned by create_task to get_task.

Test your connection

Reads your balance only. No task is created and no charge applies.

02 / TOOLS

Available tools

5 TOOLS

list_productsFree

Lists all enabled products, USD prices per solve and timeouts in one response.

get_product_schemaFree

Pass productCode to retrieve its parameter schema and example before creating a task.

create_taskProduct pricing

Creates a task using productCode, adapter and a unique requestId. Reuse the same requestId and parameters when retrying.

get_taskFree

Fallback result query by the platform id returned by create_task; prefer task.updated over polling when WebSocket is available.

get_balanceFree

Reads your current USD balance. 1 USD = 1 balance.

Only task creation charges the product price per solve. All other tools are free. Failed or expired tasks are refunded; billing and refunds appear in your asset records.

03 / REALTIME

WebSocket result delivery

Prefer WebSocket whenever your client or MCP host supports it: connect first, wait for socket.ready, then create tasks. Consume task.updated immediately; use REST query.cgi or MCP get_task only when WebSocket is unavailable, disconnected, or an update is missing.

The task WebSocket is independent of the MCP HTTP transport. A host or companion process that can set WebSocket handshake headers should connect with the same API key in the apiKey header. MCP support alone does not establish WebSocket capability: if your host cannot open a socket, use get_task with the returned id and follow nextPollAfterSeconds. Tool results expose resultDelivery with the recommended endpoint and heartbeat settings.

wss://app.nexcaptcha.net/socket/task.cgi

apiKey: YOUR_API_KEY
socket.ready → create_task → task.updated
task.taskId = create_task id
{"type":"heartbeat"} → {"type":"heartbeat.ack"}

WebSocket API keys belong in handshake HTTP headers, never URL parameters. Standalone clients use the apiKey header; browsers use the login cookie or REST queries with the apiKey header because native WebSocket cannot set custom headers. Updates belong to the authenticated user.

Use WSS on HTTPS. Reconnect with backoff after disconnect; the latest 20 terminal tasks are replayed, not a durable event history. Recover missing taskIds through query.cgi or get_task. Missing, invalid, revoked or expired credentials close with 4003; idle or unreliable connections close with 4500.

All committed state changes are pushed to this authenticated account, including tasks created through API and MCP. SUCCEEDED carries result; failures carry failure.code and nextAction. Send a heartbeat every 20 seconds and expect heartbeat.ack. After 35 seconds without heartbeat, a check running every 10 seconds closes the connection. Reconnect with backoff; never recreate a task merely because its socket disconnected. Process taskId idempotently and do not replace a terminal result with an older or replayed frame.

The container maps each user ID to one current connection per instance. A new connection replaces the previous one with close code 4009. Clients sharing an account should share one subscription through their host. A replaced client should stop reconnecting automatically. Instance capacity is at most 256 connections; 1013 means retry with backoff. Slow clients exceeding 64 queued messages or 256 KiB of queued UTF-8 data are disconnected with 4500 and should recover missing taskIds by query. A single frame is limited to 256 KiB.

API documentation · Python · Java 21

04 / WORKFLOW

From creation to result

Choose a product and read its schemalist_products → get_product_schema
Create your task oncesocket.ready → create_task(productCode, adapter, requestId)
Prefer pushed results; query only as fallbacktask.updated → get_task({"id": "TASK_ID"})

Reuse the same requestId and identical arguments when retrying creation. Prefer WebSocket results; if unavailable or disconnected, recover with get_task using id without creating another paid task. Observe nextPollAfterSeconds when polling.

Supports Streamable HTTP with protocol versions 2025-03-26, 2025-06-18 and 2025-11-25. Authenticate using Authorization: Bearer API_KEY.

Connect your AI assistant to CAPTCHA services

Choose an integration workflow

HTTP submission

Apply a result in the browser

Browser image interaction

Connect to MCP

Claude Code

Check the connection

Claude Desktop

Check the connection

Cursor

Check the connection

Codex

Check the connection

VS Code

Check the connection

Gemini CLI

Check the connection

Other clients

Check the connection

Test your connection

Available tools

WebSocket result delivery

From creation to result