MCP Server — Get Started | CaptchaSonic Docs

The CaptchaSonic MCP server gives any AI agent tools to solve CAPTCHAs: reCAPTCHA v2/v3, Cloudflare Turnstile and challenge pages, hCaptcha-style PopularCaptcha, GeeTest, MTCaptcha, AWS WAF, TikTok, Binance, OCR and more. It speaks the Model Context Protocol, so it works in Claude Code, Cursor, VS Code, Windsurf, Codex, Gemini CLI and every other MCP client.

Hosted server (recommended)

Paste one URL and your API key. Nothing to install, always up to date.

Run locally

For clients that only support local servers. Runs with npx. See Run locally.

Server URL

https://mcp.captchasonic.com

Authenticate with your CaptchaSonic API key as a bearer token:

Authorization: Bearer sonic_xxx

NOTE

This is a server URL for your MCP client, not a page to open in a browser. Get your API key from the dashboard. Solves are billed to that key exactly like direct API calls, and failed solves are refunded.

Client setup

Replace sonic_xxx with your API key.

claude mcp add --transport http captchasonic https://mcp.captchasonic.com \
  --header "Authorization: Bearer sonic_xxx"

Add to ~/.cursor/mcp.json (or Settings → MCP → Add server):

{
  "mcpServers": {
    "captchasonic": {
      "url": "https://mcp.captchasonic.com",
      "headers": { "Authorization": "Bearer sonic_xxx" }
    }
  }
}

Add to .vscode/mcp.json. VS Code prompts for the key once and stores it securely:

{
  "servers": {
    "captchasonic": {
      "type": "http",
      "url": "https://mcp.captchasonic.com",
      "headers": { "Authorization": "Bearer ${input:captchasonic-key}" }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "captchasonic-key", "description": "CaptchaSonic API key", "password": true }
  ]
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "captchasonic": {
      "serverUrl": "https://mcp.captchasonic.com",
      "headers": { "Authorization": "Bearer sonic_xxx" }
    }
  }
}

Add to ~/.codex/config.toml and export CAPTCHASONIC_API_KEY in your shell:

[mcp_servers.captchasonic]
url = "https://mcp.captchasonic.com"
bearer_token_env_var = "CAPTCHASONIC_API_KEY"

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "captchasonic": {
      "httpUrl": "https://mcp.captchasonic.com",
      "headers": { "Authorization": "Bearer sonic_xxx" }
    }
  }
}

Claude Desktop's custom connectors can't send an API key header, so use the local server. Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "captchasonic": {
      "command": "npx",
      "args": ["-y", "@captchasonic/mcp-server"],
      "env": { "SONIC_API_KEY": "sonic_xxx" }
    }
  }
}

Any other client: use the URL above with Streamable HTTP transport and an Authorization: Bearer header. If the client only supports local (stdio) servers, see Run locally.

Check it works

Ask your agent:

Check my CaptchaSonic balance.

It calls get_balance and replies with your balance. If you see ERROR_KEY_DOES_NOT_EXIST, the key in your config is wrong or revoked.

What your agent can do

Tool	Use it for
`solve_token_captcha`	reCAPTCHA v2/v3, Turnstile, Cloudflare challenge, PopularCaptcha, GeeTest, MTCaptcha. Returns a token to submit with the form.
`solve_image_captcha`	Image grids, sliders, click challenges, OCR text and audio. Returns the answer immediately.
`get_task_result`	Fetch a token that is still solving.
`get_balance`	Wallet balance and plan limits.
`list_captcha_types`	Every supported type with its required fields.

Full parameters and answer formats: Tools reference. Setting up an agent to do this on its own: For agents.