AI Agents & MCP

CaptchaSonic is agent-native. Any AI agent can solve CAPTCHAs through our MCP server — a single stdio binary that exposes three tools (health_check, get_balance, solve_captcha) over the Model Context Protocol. Because MCP is a universal standard, the same server plugs into Claude Code, Antigravity, Cursor, Windsurf, and any other MCP-compatible client. If your agent can't speak MCP, you can always call the direct SDK instead.

Golden Path for Agents

Drop this snippet into any agent and it can solve CAPTCHAs in one round trip:

# Claude Code (or any MCP client): add the server once
claude mcp add sonic --env SONIC_API_KEY=sonic_xxx -- npx -y @captchasonic/mcp-server
# Or, with no MCP — same lifecycle via curl (replace TASK_ID after createTask):
curl -s https://api.captchasonic.com/createTask  -H 'content-type: application/json' -d '{"clientKey":"sonic_xxx","task":{"type":"AntiTurnstileTaskProxyLess","websiteURL":"https://example.com","websiteKey":"0x4AAAAAAA..."}}'
curl -s https://api.captchasonic.com/getTaskResult -H 'content-type: application/json' -d '{"clientKey":"sonic_xxx","taskId":"TASK_ID"}'

Claude Code

Add the MCP server with the claude mcp add command. Pass your API key through the environment so it never lands in source control:

claude mcp add sonic --env SONIC_API_KEY=sonic_xxx -- npx -y @captchasonic/mcp-server

This runs the @captchasonic/mcp-server package via npx — no separate install step. Prefer a pinned global install? Run npm install -g @captchasonic/mcp-server once and use -- sonic-mcp as the command instead.

Once added, three tools become available to the agent:

• health_check — verify the API server is up (no API key required).
• get_balance — return the current account balance in USD.
• solve_captcha — submit a CAPTCHA (image, grid, slide, OCR, Geetest, TikTok, Binance, and more) and receive the typed solution.

You can also install the /sonic:* skills plugin for slash-command workflows that wrap the same SDK. Add the marketplace once, then install the plugin:

claude plugin marketplace add captchasonic/sonic-sdk
claude plugin install sonic@captchasonic

Once installed, three slash commands are available:

/sonic:solve      # solve a CAPTCHA from an image path or URL
/sonic:balance    # check account credits
/sonic:test-sdk   # smoke-test the SDK against the live server

Antigravity

Antigravity speaks the standard MCP protocol, so register CaptchaSonic as a generic stdio server in its MCP configuration. Add the following entry:

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

After saving, reload Antigravity's MCP servers and the health_check, get_balance, and solve_captcha tools appear in the agent's tool list.

Cursor

In Cursor, open Settings → MCP (or edit ~/.cursor/mcp.json) and add the stdio server:

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

Restart Cursor's MCP connection. The three CaptchaSonic tools are now callable from the agent.

Windsurf

In Windsurf, open Settings → Cascade → MCP Servers (or edit ~/.codeium/windsurf/mcp_config.json) and add the same stdio block:

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

Refresh the server list and CaptchaSonic's tools become available to Cascade.

Generic MCP (stdio)

Any MCP client accepts the same raw stdio config. Point command at the binary and pass SONIC_API_KEY via env. The Node runtime is published today; a Python runtime is coming soon.

Node (@captchasonic/mcp-server):

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

Python — coming soon. A uvx-installable Python MCP package is in progress. For now use the Node runtime above, or call the direct SDK.

n8n

CaptchaSonic ships an n8n community node. In your n8n instance go to Settings → Community Nodes, install n8n-nodes-captchasonic, then create a CaptchaSonic credential with your API key. The node exposes solve and balance operations you can drop into any workflow.

Without MCP (direct SDK)

If your agent can't run an MCP server, call the SDK directly. A token-style CAPTCHA is a single function call.

result = solver.solve_turnstile(
    website_url="https://example.com",
    website_key="0x4AAAAAAA...",
    proxy="http://user:pass@host:port",  # optional
)
token = result["token"]

await solver.solveTurnstile({
  websiteURL: "https://example.com",
  websiteKey: "0x4AAAAAAA...",
  proxy: "http://user:[email protected]:8080",
});

See the Python SDK and Node.js SDK pages for the full method list, or the REST API reference for the raw three-call lifecycle.