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 시작하기 가이드](/docs/mcp/get-started)부터 확인하거나, 아래의 에이전트별 안내를 참고하세요. 에이전트가 MCP를 사용할 수 없다면 [직접 SDK](#without-mcp-direct-sdk)를 호출하세요.

## 에이전트용 기본 흐름

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

```bash
# 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](/docs/mcp/for-agents)를 안내하세요. 사이트키 찾기, 적절한 도구 선택, 토큰 제출 방법을 설명하므로 추가 지시 없이도 에이전트가 작업할 수 있습니다.

---

## Claude Code

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

```bash
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를 통해 동일한 도구를 얻을 수 있습니다.

### Claude 스킬 플러그인 (권장)

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

```bash
/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 서버로 등록하세요:

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

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

---

## Cursor

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

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

---

## Windsurf

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

```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 설정은 [시작하기 가이드](/docs/mcp/get-started)에 있습니다.

로컬 서버만 실행하는 클라이언트는 표준 stdio 블록을 사용하세요([로컬 실행](/docs/mcp/run-locally) 참고):

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

---

## n8n

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

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

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

---

## MCP 없이 (직접 SDK)

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

<LangTabs>
  <LangTabs.Tab label="Python">

<Snippet sdk="python" region="solveTurnstile" />

  </LangTabs.Tab>
  <LangTabs.Tab label="Node">

<Snippet sdk="typescript" region="solveTurnstile" />

  </LangTabs.Tab>
</LangTabs>

전체 메서드 목록은 [Python SDK](/docs/clients-sdks/python) 및 [Node.js SDK](/docs/clients-sdks/nodejs) 페이지를, 원시 3단계 호출 흐름은 [REST API 레퍼런스](/docs/api)를 참고하세요.
