CaptchaSonic est **conçu pour les agents**. Tout agent IA peut résoudre des CAPTCHA via notre **serveur MCP**, disponible de deux façons :

- **Hébergé :** `https://mcp.captchasonic.com` avec votre clé API comme jeton bearer. Rien à installer. Recommandé.
- **Local :** `npx -y @captchasonic/mcp-server` via stdio, pour les clients qui ne prennent en charge que les serveurs locaux.

Les deux exposent les mêmes cinq outils : `solve_token_captcha`, `solve_image_captcha`, `get_task_result`, `get_balance` et `list_captcha_types`. Commencez par le [guide de démarrage MCP](/docs/mcp/get-started) pour chaque client, ou consultez les notes par agent ci-dessous. Si votre agent ne peut pas parler MCP, appelez plutôt le [SDK direct](#without-mcp-direct-sdk).

## Parcours express pour les agents

Ajoutez ceci à n'importe quel agent : il peut résoudre des CAPTCHA en un seul aller-retour :

```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]
> Orientez un agent vers [MCP pour les agents IA](/docs/mcp/for-agents). Il explique comment trouver les sitekeys, choisir le bon outil et soumettre le jeton, afin que l'agent puisse travailler sans instructions supplémentaires.

---

## Claude Code

Ajoutez le serveur hébergé :

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

Vous préférez l'exécuter en local ? `claude mcp add captchasonic --env SONIC_API_KEY=sonic_xxx -- npx -y @captchasonic/mcp-server` vous donne les mêmes outils via stdio.

### Plugin de compétences Claude (recommandé)

Pour des flux guidés, installez le **plugin de compétences CaptchaSonic** officiel. Il regroupe trois compétences Claude et connecte le serveur MCP hébergé à l'aide de la variable d'environnement `SONIC_API_KEY`. Exportez votre clé, démarrez Claude Code, puis exécutez :

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

Trois compétences guident ensuite l'agent dans les flux courants :

- **`captchasonic-setup`** — configuration initiale et vérification du MCP.
- **`captchasonic-solve`** — résolution de tout type de CAPTCHA, étape par étape.
- **`captchasonic-balance`** — consultation du solde et de l'état des crédits.

> [!TIP]
> Utilisez `get_balance` (ou la compétence `captchasonic-balance`) comme garde-fou avant un lot de résolutions, afin que l'agent puisse s'arrêter tôt si les crédits sont insuffisants.

---

## Antigravity

Enregistrez CaptchaSonic dans la configuration MCP d'Antigravity comme serveur stdio local :

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

Rechargez les serveurs MCP d'Antigravity et les outils CaptchaSonic apparaissent dans la liste d'outils de l'agent.

---

## Cursor

Ouvrez **Paramètres → MCP** (ou modifiez `~/.cursor/mcp.json`) et ajoutez le serveur hébergé :

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

---

## Windsurf

Ouvrez **Paramètres → Cascade → MCP Servers** (ou modifiez `~/.codeium/windsurf/mcp_config.json`) :

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

---

## MCP générique

Tout client MCP qui prend en charge les serveurs distants : utilisez `https://mcp.captchasonic.com` avec le transport Streamable HTTP et l'en-tête `Authorization: Bearer sonic_xxx`. Les configurations pour VS Code, Codex et Gemini CLI se trouvent dans le [guide de démarrage](/docs/mcp/get-started).

Les clients qui ne exécutent que des serveurs locaux utilisent le bloc stdio standard (voir [Exécution en local](/docs/mcp/run-locally)) :

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

---

## n8n

CaptchaSonic dispose d'un **nœud communautaire n8n vérifié** ([fiche n8n.io](https://n8n.io/integrations/captchasonic/)) qui encapsule plus de 20 types de CAPTCHA dans des nœuds de workflow glisser-déposer. Il fonctionne aussi bien comme nœud autonome que comme outil du nœud Agent IA de n8n.

→ **[Guide complet d'intégration n8n](/docs/integrations/n8n)** — installation pas à pas, configuration des identifiants, 4 recettes de workflow, configuration par type de CAPTCHA, gestion des erreurs et dépannage.

**Installation rapide :** Paramètres → Nœuds communautaires → installez `n8n-nodes-captchasonic` → créez un identifiant CaptchaSonic avec votre clé API → c'est terminé.

---

## Sans MCP (SDK direct)

Si votre agent ne peut pas utiliser MCP, appelez directement le SDK. Un CAPTCHA de type jeton se résume à un seul appel de fonction.

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

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

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

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

  </LangTabs.Tab>
</LangTabs>

Consultez les pages [SDK Python](/docs/clients-sdks/python) et [SDK Node.js](/docs/clients-sdks/nodejs) pour la liste complète des méthodes, ou la [référence de l'API REST](/docs/api) pour le cycle brut à trois appels.
