CaptchaSonic は **エージェントネイティブ** です。任意の AI エージェントが **MCP サーバー** を通じて CAPTCHA を解決できます。利用方法は 2 つあります。

- **ホスト型:** API キーをベアラートークンとして使う `https://mcp.captchasonic.com`。インストールは不要です。推奨です。
- **ローカル:** ローカルサーバーしか対応していないクライアント向けに、stdio 経由で `npx -y @captchasonic/mcp-server` を実行します。

どちらでも同じ 5 つのツールを利用できます: `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) を呼び出してください。

## エージェント向けゴールデンパス

任意のエージェントに以下を渡すと、1 回のやり取りで 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 スキルプラグイン** をインストールしてください。3 つの Claude スキルがまとめられており、`SONIC_API_KEY` 環境変数を使ってホスト型 MCP サーバーに接続します。キーを export してから Claude Code を起動し、次を実行してください。

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

これで 3 つのスキルが、よくあるワークフローをエージェントに案内します。

- **`captchasonic-setup`** — 初回の MCP セットアップと動作確認です。
- **`captchasonic-solve`** — どの CAPTCHA 種別でも、手順に沿って解決を案内します。
- **`captchasonic-balance`** — アカウント残高とクレジット状況を確認します。

> [!TIP]
> 一括で解決を行う前に `get_balance`（または `captchasonic-balance` スキル）で残高を確認しておくと、クレジットが少なくなったときにエージェントが早めに停止できます。

---

## Antigravity

Antigravity の MCP 設定に、ローカルの stdio サーバーとして CaptchaSonic を登録します。

```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 は 1 回の関数呼び出しで済みます。

<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) をご覧ください。
