Skip to content
CaptchaSonic

AI 에이전트 & MCP

Claude Code, Cursor, Windsurf, Antigravity, n8n 등 모든 AI 에이전트에서 CaptchaSonic을 사용하세요. 호스팅 MCP 서버(mcp.captchasonic.com), 로컬 npx 서버, 또는 SDK를 직접 사용할 수 있습니다.

CaptchaSonic은 에이전트 네이티브입니다. 모든 AI 에이전트는 두 가지 방식으로 제공되는 MCP 서버를 통해 CAPTCHA를 풀 수 있습니다:

  • 호스팅: API 키를 bearer 토큰으로 사용하는 https://mcp.captchasonic.com. 설치할 것이 없습니다. 권장 방식입니다.
  • 로컬: stdio를 통한 npx -y @captchasonic/mcp-server. 로컬 서버만 지원하는 클라이언트용입니다.

두 방식 모두 동일한 다섯 가지 도구를 제공합니다: solve_token_captcha, solve_image_captcha, get_task_result, get_balance, list_captcha_types. 모든 클라이언트에 대해서는 MCP 시작하기 가이드부터 확인하거나, 아래의 에이전트별 안내를 참고하세요. 에이전트가 MCP를 사용할 수 없다면 직접 SDK를 호출하세요.

에이전트용 기본 흐름

어떤 에이전트에든 아래 내용을 넣으면 한 번의 요청으로 CAPTCHA를 풀 수 있습니다:

# Claude Code (or any MCP client): add the hosted server once
claude mcp add --transport http captchasonic https://mcp.captchasonic.com --header "Authorization: Bearer sonic_xxx"
# Or, with no MCP — the same lifecycle via curl (replace TASK_ID after createTask):
curl -s https://api.captchasonic.com/createTask -H 'content-type: application/json' -d '{"apiKey":"sonic_xxx","task":{"type":"AntiTurnstileTaskProxyLess","websiteURL":"https://example.com","websiteKey":"0x4AAAAAAA..."}}'
curl -s https://api.captchasonic.com/getTaskResult -H 'content-type: application/json' -d '{"apiKey":"sonic_xxx","taskId":"TASK_ID"}'

TIP

에이전트에게 AI 에이전트를 위한 MCP를 안내하세요. 사이트키 찾기, 적절한 도구 선택, 토큰 제출 방법을 설명하므로 추가 지시 없이도 에이전트가 작업할 수 있습니다.


Claude Code

호스팅 서버를 추가합니다:

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

로컬에서 실행하고 싶다면 claude mcp add captchasonic --env SONIC_API_KEY=sonic_xxx -- npx -y @captchasonic/mcp-server를 사용하면 stdio를 통해 동일한 도구를 얻을 수 있습니다.

안내형 워크플로가 필요하다면 공식 CaptchaSonic 스킬 플러그인을 설치하세요. 이 플러그인은 Claude 스킬 3종을 포함하며, SONIC_API_KEY 환경 변수를 사용해 호스팅 MCP 서버에 연결합니다. 키를 export한 뒤 Claude Code를 실행하고 다음을 입력하세요:

/plugin marketplace add Captcha-Sonic/Agent-skills
/plugin install captchasonic

이후 세 가지 스킬이 일반적인 워크플로를 에이전트에게 안내합니다:

  • captchasonic-setup — 최초 MCP 설정 및 검증.
  • captchasonic-solve — 단계별 안내와 함께 모든 CAPTCHA 유형 풀기.
  • captchasonic-balance — 계정 잔액 및 크레딧 상태 확인.

TIP

대량 풀이를 시작하기 전에 get_balance(또는 captchasonic-balance 스킬)로 먼저 확인하세요. 크레딧이 부족하면 에이전트가 일찍 중단할 수 있습니다.


Antigravity

Antigravity의 MCP 설정에 CaptchaSonic을 로컬 stdio 서버로 등록하세요:

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

Antigravity에서 MCP 서버를 다시 로드하면 CaptchaSonic 도구가 에이전트의 도구 목록에 나타납니다.


Cursor

Settings → MCP를 열거나 ~/.cursor/mcp.json을 편집하여 호스팅 서버를 추가하세요:

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

Windsurf

Settings → Cascade → MCP Servers를 열거나 ~/.codeium/windsurf/mcp_config.json을 편집하세요:

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

일반 MCP

원격 서버를 지원하는 모든 MCP 클라이언트는 Streamable HTTP 전송 방식과 Authorization: Bearer sonic_xxx 헤더를 사용해 https://mcp.captchasonic.com에 연결할 수 있습니다. VS Code, Codex, Gemini CLI 설정은 시작하기 가이드에 있습니다.

로컬 서버만 실행하는 클라이언트는 표준 stdio 블록을 사용하세요(로컬 실행 참고):

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

n8n

CaptchaSonic은 20종 이상의 CAPTCHA 유형을 드래그 앤 드롭 워크플로 노드로 감싼 검증된 n8n 커뮤니티 노드(n8n.io 등록 페이지)를 제공합니다. 독립 노드로도, n8n AI Agent 노드의 도구로도 사용할 수 있습니다.

→ n8n 통합 가이드 전체 — 단계별 설치, 자격 증명 설정, 워크플로 예제 4가지, CAPTCHA 유형별 설정, 오류 처리 패턴, 문제 해결을 다룹니다.

빠른 설치: Settings → Community Nodes → n8n-nodes-captchasonic 설치 → API 키로 CaptchaSonic 자격 증명 생성 → 완료.


MCP 없이 (직접 SDK)

에이전트가 MCP를 사용할 수 없다면 SDK를 직접 호출하세요. 토큰 방식 CAPTCHA는 함수 호출 한 번으로 끝납니다.

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

전체 메서드 목록은 Python SDK 및 Node.js SDK 페이지를, 원시 3단계 호출 흐름은 REST API 레퍼런스를 참고하세요.