CaptchaSonic ist **agent-nativ**. Jeder KI-Agent kann CAPTCHAs über unseren **MCP-Server** lösen, der auf zwei Wegen verfügbar ist:

- **Gehostet:** `https://mcp.captchasonic.com` mit Ihrem API-Schlüssel als Bearer-Token. Keine Installation nötig. Empfohlen.
- **Lokal:** `npx -y @captchasonic/mcp-server` über stdio, für Clients, die nur lokale Server unterstützen.

Beide stellen dieselben fünf Tools bereit: `solve_token_captcha`, `solve_image_captcha`, `get_task_result`, `get_balance` und `list_captcha_types`. Beginnen Sie für jeden Client mit dem [MCP-Einstiegsleitfaden](/docs/mcp/get-started), oder lesen Sie die Hinweise zu den einzelnen Agenten unten. Wenn Ihr Agent kein MCP sprechen kann, rufen Sie stattdessen das [direkte SDK](#without-mcp-direct-sdk) auf.

## Golden Path für Agenten

Fügen Sie dies in einen beliebigen Agenten ein, dann kann er CAPTCHAs in einem einzigen Durchlauf lösen:

```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]
> Verweisen Sie einen Agenten auf [MCP für KI-Agenten](/docs/mcp/for-agents). Dort wird erklärt, wie Sitekeys gefunden, das passende Tool gewählt und das Token übermittelt wird, damit der Agent ohne weitere Anweisungen arbeiten kann.

---

## Claude Code

Fügen Sie den gehosteten Server hinzu:

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

Lieber lokal betreiben? `claude mcp add captchasonic --env SONIC_API_KEY=sonic_xxx -- npx -y @captchasonic/mcp-server` stellt dieselben Tools über stdio bereit.

### Claude-Skill-Plugin (empfohlen)

Für geführte Abläufe installieren Sie das offizielle **CaptchaSonic-Skill-Plugin**. Es enthält drei Claude-Skills und verbindet den gehosteten MCP-Server über die Umgebungsvariable `SONIC_API_KEY`. Exportieren Sie Ihren Schlüssel, starten Sie Claude Code und führen Sie dann aus:

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

Anschließend führen drei Skills den Agenten durch die gängigen Abläufe:

- **`captchasonic-setup`** — Ersteinrichtung und Prüfung des MCP-Servers.
- **`captchasonic-solve`** — Lösen jedes CAPTCHA-Typs mit schrittweiser Anleitung.
- **`captchasonic-balance`** — Kontostand und Guthaben prüfen.

> [!TIP]
> Verwenden Sie `get_balance` (oder den Skill `captchasonic-balance`) als Prüfung vor einer Serie von Lösungen, damit der Agent bei niedrigem Guthaben früh anhalten kann.

---

## Antigravity

Registrieren Sie CaptchaSonic in der MCP-Konfiguration von Antigravity als lokalen stdio-Server:

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

Laden Sie die MCP-Server von Antigravity neu, dann erscheinen die CaptchaSonic-Tools in der Tool-Liste des Agenten.

---

## Cursor

Öffnen Sie **Einstellungen → MCP** (oder bearbeiten Sie `~/.cursor/mcp.json`) und fügen Sie den gehosteten Server hinzu:

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

---

## Windsurf

Öffnen Sie **Einstellungen → Cascade → MCP Servers** (oder bearbeiten Sie `~/.codeium/windsurf/mcp_config.json`):

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

---

## Generisches MCP

Jeder MCP-Client, der Remote-Server unterstützt: Verwenden Sie `https://mcp.captchasonic.com` mit dem Streamable-HTTP-Transport und dem Header `Authorization: Bearer sonic_xxx`. Konfigurationen für VS Code, Codex und Gemini CLI finden Sie im [Einstiegsleitfaden](/docs/mcp/get-started).

Clients, die nur lokale Server ausführen, verwenden den Standard-stdio-Block (siehe [Lokal ausführen](/docs/mcp/run-locally)):

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

---

## n8n

CaptchaSonic bietet einen **verifizierten n8n-Community-Node** ([n8n.io-Eintrag](https://n8n.io/integrations/captchasonic/)), der mehr als 20 CAPTCHA-Typen in Drag-and-Drop-Workflow-Nodes kapselt. Er funktioniert sowohl als eigenständiger Node als auch als Tool für den AI-Agent-Node von n8n.

→ **[Vollständige n8n-Integrationsanleitung](/docs/integrations/n8n)** — Schritt-für-Schritt-Installation, Credential-Einrichtung, 4 Workflow-Rezepte, Konfiguration je CAPTCHA-Typ, Fehlerbehandlung und Fehlersuche.

**Schnellinstallation:** Einstellungen → Community Nodes → `n8n-nodes-captchasonic` installieren → CaptchaSonic-Credential mit Ihrem API-Schlüssel anlegen → fertig.

---

## Ohne MCP (direktes SDK)

Wenn Ihr Agent MCP nicht nutzen kann, rufen Sie das SDK direkt auf. Ein CAPTCHA vom Token-Typ ist ein einziger Funktionsaufruf.

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

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

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

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

  </LangTabs.Tab>
</LangTabs>

Die vollständige Methodenliste finden Sie auf den Seiten zum [Python-SDK](/docs/clients-sdks/python) und [Node.js-SDK](/docs/clients-sdks/nodejs), den rohen dreistufigen Ablauf in der [REST-API-Referenz](/docs/api).
