A CaptchaSonic é **nativa para agentes**. Qualquer agente de IA pode resolver CAPTCHAs pelo nosso **servidor MCP**, disponível de duas formas:

- **Hospedado:** `https://mcp.captchasonic.com` com a sua API key como bearer token. Não é preciso instalar nada. Recomendado.
- **Local:** `npx -y @captchasonic/mcp-server` via stdio, para clientes que só suportam servidores locais.

Ambos expõem as mesmas cinco ferramentas: `solve_token_captcha`, `solve_image_captcha`, `get_task_result`, `get_balance` e `list_captcha_types`. Comece pelo [guia de Primeiros passos com MCP](/docs/mcp/get-started) para cada cliente, ou leia as notas por agente abaixo. Se o seu agente não falar MCP, use o [SDK direto](#without-mcp-direct-sdk).

## Caminho rápido para agentes

Adicione isto a qualquer agente e ele conseguirá resolver CAPTCHAs em uma única ida e volta:

```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]
> Aponte um agente para [MCP para agentes de IA](/docs/mcp/for-agents). Ele explica como encontrar sitekeys, escolher a ferramenta certa e enviar o token, para que o agente funcione sem instruções adicionais.

---

## Claude Code

Adicione o servidor hospedado:

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

Prefere executar localmente? `claude mcp add captchasonic --env SONIC_API_KEY=sonic_xxx -- npx -y @captchasonic/mcp-server` oferece as mesmas ferramentas via stdio.

### Plugin de skills do Claude (recomendado)

Para fluxos guiados, instale o **plugin oficial de skills da CaptchaSonic**. Ele reúne três skills do Claude e conecta o servidor MCP hospedado usando a variável de ambiente `SONIC_API_KEY`. Exporte a sua chave, inicie o Claude Code e execute:

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

Três skills então guiam o agente pelos fluxos comuns:

- **`captchasonic-setup`** — configuração inicial e verificação do MCP.
- **`captchasonic-solve`** — resolve qualquer tipo de CAPTCHA com orientação passo a passo.
- **`captchasonic-balance`** — consulta o saldo da conta e o status de créditos.

> [!TIP]
> Use `get_balance` (ou a skill `captchasonic-balance`) como guarda antes de um lote de resoluções, para que o agente pare cedo caso os créditos estejam acabando.

---

## Antigravity

Registre a CaptchaSonic na configuração de MCP do Antigravity como um servidor stdio local:

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

Recarregue os servidores MCP do Antigravity e as ferramentas da CaptchaSonic aparecerão na lista de ferramentas do agente.

---

## Cursor

Abra **Settings → MCP** (ou edite `~/.cursor/mcp.json`) e adicione o servidor hospedado:

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

---

## Windsurf

Abra **Settings → Cascade → MCP Servers** (ou edite `~/.codeium/windsurf/mcp_config.json`):

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

---

## MCP genérico

Qualquer cliente MCP que suporte servidores remotos: use `https://mcp.captchasonic.com` com o transporte Streamable HTTP e o header `Authorization: Bearer sonic_xxx`. As configurações para VS Code, Codex e Gemini CLI estão no [guia de Primeiros passos](/docs/mcp/get-started).

Clientes que só executam servidores locais usam o bloco stdio padrão (veja [Executar localmente](/docs/mcp/run-locally)):

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

---

## n8n

A CaptchaSonic tem um **node comunitário verificado para n8n** ([página no n8n.io](https://n8n.io/integrations/captchasonic/)) que encapsula mais de 20 tipos de captcha em nós de fluxo de trabalho arrastar e soltar. Ele funciona tanto como node independente quanto como ferramenta para o node AI Agent do n8n.

→ **[Guia completo de integração com o n8n](/docs/integrations/n8n)** — instalação passo a passo, configuração de credenciais, 4 receitas de fluxo de trabalho, configuração por tipo de captcha, padrões de tratamento de erros e solução de problemas.

**Instalação rápida:** Settings → Community Nodes → instale `n8n-nodes-captchasonic` → crie a credencial CaptchaSonic com a sua API key → pronto.

---

## Sem MCP (SDK direto)

Se o seu agente não puder usar MCP, chame o SDK diretamente. Um CAPTCHA do tipo token é uma única chamada de função.

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

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

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

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

  </LangTabs.Tab>
</LangTabs>

Veja as páginas do [SDK Python](/docs/clients-sdks/python) e do [SDK Node.js](/docs/clients-sdks/nodejs) para a lista completa de métodos, ou a [referência da API REST](/docs/api) para o ciclo de três chamadas bruto.
