CaptchaSonic es **nativo para agentes**. Cualquier agente de IA puede resolver CAPTCHAs a través de nuestro **servidor MCP**, disponible de dos formas:

- **Alojado:** `https://mcp.captchasonic.com` con tu clave API como token bearer. No requiere instalación. Recomendado.
- **Local:** `npx -y @captchasonic/mcp-server` por stdio, para clientes que solo admiten servidores locales.

Ambos exponen las mismas cinco herramientas: `solve_token_captcha`, `solve_image_captcha`, `get_task_result`, `get_balance` y `list_captcha_types`. Empieza con la [guía de inicio de MCP](/docs/mcp/get-started) para cada cliente, o consulta las notas por agente más abajo. Si tu agente no puede hablar MCP, llama al [SDK directo](#without-mcp-direct-sdk) en su lugar.

## Ruta rápida para agentes

Pega esto en cualquier agente y podrá resolver CAPTCHAs en un solo viaje de ida y vuelta:

```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]
> Dirige un agente a [MCP para agentes de IA](/docs/mcp/for-agents). Explica cómo encontrar los sitekeys, elegir la herramienta correcta y enviar el token, para que el agente funcione sin más instrucciones.

---

## Claude Code

Añade el servidor alojado:

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

¿Prefieres ejecutarlo localmente? `claude mcp add captchasonic --env SONIC_API_KEY=sonic_xxx -- npx -y @captchasonic/mcp-server` te ofrece las mismas herramientas por stdio.

### Plugin de skills de Claude (recomendado)

Para flujos de trabajo guiados, instala el **plugin oficial de skills de CaptchaSonic**. Incluye tres skills de Claude y conecta el servidor MCP alojado usando la variable de entorno `SONIC_API_KEY`. Exporta tu clave, inicia Claude Code y luego ejecuta:

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

Tres skills guían al agente en los flujos de trabajo habituales:

- **`captchasonic-setup`** — configuración inicial de MCP y verificación.
- **`captchasonic-solve`** — resuelve cualquier tipo de CAPTCHA con orientación paso a paso.
- **`captchasonic-balance`** — consulta el saldo de la cuenta y el estado de los créditos.

> [!TIP]
> Usa `get_balance` (o la skill `captchasonic-balance`) como guardia antes de un lote de resoluciones, para que el agente pueda detenerse pronto si los créditos se agotan.

---

## Antigravity

Registra CaptchaSonic en la configuración MCP de Antigravity como servidor stdio local:

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

Recarga los servidores MCP de Antigravity y las herramientas de CaptchaSonic aparecerán en la lista de herramientas del agente.

---

## Cursor

Abre **Settings → MCP** (o edita `~/.cursor/mcp.json`) y añade el servidor alojado:

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

---

## Windsurf

Abre **Settings → Cascade → MCP Servers** (o edita `~/.codeium/windsurf/mcp_config.json`):

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

---

## MCP genérico

Cualquier cliente MCP que admita servidores remotos: usa `https://mcp.captchasonic.com` con transporte Streamable HTTP y el encabezado `Authorization: Bearer sonic_xxx`. Las configuraciones de VS Code, Codex y Gemini CLI están en la [guía de inicio](/docs/mcp/get-started).

Los clientes que solo ejecutan servidores locales usan el bloque stdio estándar (ver [Ejecutar en local](/docs/mcp/run-locally)):

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

---

## n8n

CaptchaSonic tiene un **nodo comunitario verificado para n8n** ([ficha en n8n.io](https://n8n.io/integrations/captchasonic/)) que envuelve más de 20 tipos de CAPTCHA en nodos de flujo de trabajo de arrastrar y soltar. Funciona como nodo independiente y como herramienta para el nodo AI Agent de n8n.

→ **[Guía completa de integración con n8n](/docs/integrations/n8n)** — instalación paso a paso, configuración de credenciales, 4 recetas de flujos de trabajo, configuración por tipo de CAPTCHA, patrones de manejo de errores y solución de problemas.

**Instalación rápida:** Settings → Community Nodes → instala `n8n-nodes-captchasonic` → crea la credencial de CaptchaSonic con tu clave API → listo.

---

## Sin MCP (SDK directo)

Si tu agente no puede usar MCP, llama al SDK directamente. Un CAPTCHA de tipo token es una sola llamada a función.

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

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

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

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

  </LangTabs.Tab>
</LangTabs>

Consulta las páginas del [SDK de Python](/docs/clients-sdks/python) y del [SDK de Node.js](/docs/clients-sdks/nodejs) para la lista completa de métodos, o la [referencia de la API REST](/docs/api) para el ciclo de tres llamadas en bruto.
