CaptchaSonic MCP 서버는 모든 AI 에이전트에 CAPTCHA 해결 도구를 제공합니다. reCAPTCHA v2/v3, Cloudflare Turnstile 및 챌린지 페이지, hCaptcha 스타일의 PopularCaptcha, GeeTest, MTCaptcha, AWS WAF, TikTok, Binance, OCR 등을 지원합니다. [Model Context Protocol](https://modelcontextprotocol.io)을 사용하므로 Claude Code, Cursor, VS Code, Windsurf, Codex, Gemini CLI 등 모든 MCP 클라이언트에서 동작합니다.

  
    URL 하나와 API 키만 붙여 넣으세요. 설치할 것이 없고 항상 최신 상태입니다.
  
  
    로컬 서버만 지원하는 클라이언트용입니다. `npx`로 실행합니다. [로컬 실행](/docs/mcp/run-locally)을 참고하세요.
  

## 서버 URL

```text
https://mcp.captchasonic.com
```

CaptchaSonic API 키를 bearer 토큰으로 사용해 인증하세요:

```text
Authorization: Bearer sonic_xxx
```

> [!NOTE]
> 이 주소는 MCP 클라이언트용 서버 URL이며, 브라우저에서 열 페이지가 아닙니다. API 키는 [대시보드](https://my.captchasonic.com)에서 발급받으세요. 해결 요금은 직접 API 호출과 똑같이 이 키로 청구되며, 실패한 해결은 환불됩니다.

## 클라이언트 설정

`sonic_xxx`를 본인의 API 키로 바꾸세요.

<LangTabs>
  <LangTabs.Tab label="Claude Code">

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

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

`~/.cursor/mcp.json`에 추가하세요(또는 **Settings → MCP → Add server**를 사용하세요):

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

  </LangTabs.Tab>
  <LangTabs.Tab label="VS Code">

`.vscode/mcp.json`에 추가하세요. VS Code가 키를 한 번 물어본 뒤 안전하게 저장합니다:

```json
{
  "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 }
  ]
}
```

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

`~/.codeium/windsurf/mcp_config.json`에 추가하세요:

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

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

`~/.codex/config.toml`에 추가하고 셸에서 `CAPTCHASONIC_API_KEY`를 export하세요:

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

  </LangTabs.Tab>
  <LangTabs.Tab label="Gemini CLI">

`~/.gemini/settings.json`에 추가하세요:

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

  </LangTabs.Tab>
  <LangTabs.Tab label="Claude Desktop">

Claude Desktop의 커스텀 커넥터는 API 키 헤더를 보낼 수 없으므로 로컬 서버를 사용하세요. `claude_desktop_config.json`(**Settings → Developer → Edit Config**)에 추가하세요:

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

  </LangTabs.Tab>
</LangTabs>

그 밖의 클라이언트는 위 URL을 Streamable HTTP 전송 방식과 `Authorization: Bearer` 헤더와 함께 사용하세요. 클라이언트가 로컬(stdio) 서버만 지원한다면 [로컬 실행](/docs/mcp/run-locally)을 참고하세요.

## 동작 확인

에이전트에게 물어보세요:

```text
Check my CaptchaSonic balance.
```

에이전트가 `get_balance`를 호출하고 잔액을 알려줍니다. `ERROR_KEY_DOES_NOT_EXIST`가 보이면 설정의 키가 잘못되었거나 취소된 것입니다.

## 에이전트가 할 수 있는 일

| 도구 | 용도 |
|---|---|
| `solve_token_captcha` | reCAPTCHA v2/v3, Turnstile, Cloudflare 챌린지, PopularCaptcha, GeeTest, MTCaptcha. 폼과 함께 제출할 토큰을 반환합니다. |
| `solve_image_captcha` | 이미지 그리드, 슬라이더, 클릭 챌린지, OCR 텍스트 및 오디오. 답을 즉시 반환합니다. |
| `get_task_result` | 아직 해결 중인 토큰을 가져옵니다. |
| `get_balance` | 지갑 잔액과 요금제 한도. |
| `list_captcha_types` | 지원되는 모든 유형과 필수 필드. |

전체 매개변수와 응답 형식: [도구 참조](/docs/mcp/tools). 에이전트가 이를 스스로 수행하도록 설정하기: [에이전트용](/docs/mcp/for-agents).
