captchasonic-setup

CaptchaSonic MCP Server Setup

Set up the CaptchaSonic MCP server so your AI agent can solve CAPTCHAs.

Step 1: Check Prerequisites

Verify Node.js is installed (v18+):

node --version

If not installed, the user needs to install Node.js from nodejs.org.

Step 2: Get the API Key

Ask the user for their CaptchaSonic API key. It starts with sonic_.

If they don't have one: "Register for free at captchasonic.com to get your API key."

Step 3: Add the MCP Server

Option A: Claude Code CLI (recommended)

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

Replace sonic_xxxx with the user's actual API key.

Option B: Global Install + CLI

npm install -g @captchasonic/mcp-server
claude mcp add sonic --env SONIC_API_KEY=sonic_xxxx -- sonic-mcp

Option C: Claude Desktop

Edit the Claude Desktop config file.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this to the mcpServers section:

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

Then restart Claude Desktop.

Option D: Antigravity IDE

Add MCP server configuration in your Antigravity settings pointing to:

npx -y @captchasonic/mcp-server

with environment variable SONIC_API_KEY=sonic_xxxx.

Step 4: Verify Health Check

After adding the server, run a health check to confirm connectivity:

Tool: health_check
Arguments: {}

Expected response:

healthy: true
version: x.x.x

If the health check fails:

• Check your internet connection
• Verify Node.js is installed and npx is available
• Try running npx -y @captchasonic/mcp-server manually to see errors

Step 5: Verify API Key

Run a balance check to confirm the API key is valid: