CaptchaSonic được thiết kế **cho agent**. Bất kỳ AI agent nào cũng có thể giải CAPTCHA thông qua **máy chủ MCP** của chúng tôi, theo hai cách:

- **Hosted:** `https://mcp.captchasonic.com` với API key của bạn làm bearer token. Không cần cài đặt. Khuyến nghị.
- **Local:** `npx -y @captchasonic/mcp-server` qua stdio, dành cho các client chỉ hỗ trợ máy chủ cục bộ.

Cả hai đều cung cấp cùng năm công cụ: `solve_token_captcha`, `solve_image_captcha`, `get_task_result`, `get_balance` và `list_captcha_types`. Bắt đầu với [hướng dẫn MCP Get Started](/docs/mcp/get-started) cho mọi client, hoặc đọc ghi chú theo từng agent bên dưới. Nếu agent của bạn không hỗ trợ MCP, hãy gọi [SDK trực tiếp](#without-mcp-direct-sdk).

## Đường dẫn nhanh cho Agent

Thêm đoạn sau vào bất kỳ agent nào, agent đó có thể giải CAPTCHA chỉ trong một lượt:

```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]
> Hướng dẫn agent đến [MCP cho AI Agents](/docs/mcp/for-agents). Trang đó giải thích cách tìm sitekey, chọn đúng công cụ và gửi token, để agent làm việc mà không cần thêm hướng dẫn.

---

## Claude Code

Thêm máy chủ hosted:

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

Muốn chạy cục bộ? `claude mcp add captchasonic --env SONIC_API_KEY=sonic_xxx -- npx -y @captchasonic/mcp-server` cung cấp cùng công cụ qua stdio.

### Plugin skill cho Claude (khuyến nghị)

Để có các quy trình có hướng dẫn, hãy cài **plugin skill CaptchaSonic** chính thức. Plugin này gồm ba Claude skill và kết nối máy chủ MCP hosted bằng biến môi trường `SONIC_API_KEY`. Xuất key của bạn, khởi động Claude Code, rồi chạy:

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

Ba skill sau sẽ hướng dẫn agent qua các quy trình thường dùng:

- **`captchasonic-setup`** — thiết lập MCP lần đầu và kiểm tra.
- **`captchasonic-solve`** — giải mọi loại CAPTCHA với hướng dẫn từng bước.
- **`captchasonic-balance`** — kiểm tra số dư tài khoản và trạng thái credit.

> [!TIP]
> Dùng `get_balance` (hoặc skill `captchasonic-balance`) làm bước kiểm tra trước một loạt lượt giải, để agent có thể dừng sớm nếu credit sắp hết.

---

## Antigravity

Đăng ký CaptchaSonic trong cấu hình MCP của Antigravity như một máy chủ stdio cục bộ:

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

Tải lại các máy chủ MCP của Antigravity, các công cụ CaptchaSonic sẽ xuất hiện trong danh sách công cụ của agent.

---

## Cursor

Mở **Settings → MCP** (hoặc sửa `~/.cursor/mcp.json`) và thêm máy chủ hosted:

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

---

## Windsurf

Mở **Settings → Cascade → MCP Servers** (hoặc sửa `~/.codeium/windsurf/mcp_config.json`):

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

---

## MCP chung

Mọi MCP client hỗ trợ máy chủ từ xa: dùng `https://mcp.captchasonic.com` với transport Streamable HTTP và header `Authorization: Bearer sonic_xxx`. Cấu hình cho VS Code, Codex và Gemini CLI có trong [hướng dẫn Get Started](/docs/mcp/get-started).

Các client chỉ chạy máy chủ cục bộ dùng khối stdio tiêu chuẩn (xem [Chạy cục bộ](/docs/mcp/run-locally)):

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

---

## n8n

CaptchaSonic có **node cộng đồng n8n đã được xác minh** ([trang n8n.io](https://n8n.io/integrations/captchasonic/)), bao bọc hơn 20 loại captcha thành các node kéo-thả trong workflow. Node này hoạt động cả như một node độc lập lẫn như một công cụ cho node AI Agent của n8n.

→ **[Hướng dẫn tích hợp n8n đầy đủ](/docs/integrations/n8n)** — cài đặt từng bước, thiết lập credential, 4 mẫu workflow, cấu hình theo từng loại captcha, mẫu xử lý lỗi và khắc phục sự cố.

**Cài đặt nhanh:** Settings → Community Nodes → cài `n8n-nodes-captchasonic` → tạo credential CaptchaSonic với API key của bạn → xong.

---

## Không dùng MCP (SDK trực tiếp)

Nếu agent của bạn không dùng được MCP, hãy gọi SDK trực tiếp. Một CAPTCHA dạng token chỉ cần một lần gọi hàm.

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

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

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

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

  </LangTabs.Tab>
</LangTabs>

Xem các trang [Python SDK](/docs/clients-sdks/python) và [Node.js SDK](/docs/clients-sdks/nodejs) để có danh sách đầy đủ các phương thức, hoặc [tham chiếu REST API](/docs/api) để xem vòng đời ba lệnh gọi thô.
