AI Agents & MCP
Dùng CaptchaSonic từ bất kỳ AI agent nào — Claude Code, Cursor, Windsurf, Antigravity, n8n — qua máy chủ MCP được host tại mcp.captchasonic.com, máy chủ npx chạy cục bộ, hoặc gọi trực tiếp SDK.
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.comvớ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-serverqua 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 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.
Đườ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:
# 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. 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:
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:
/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ộ:
{
"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:
{
"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):
{
"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.
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ộ):
{
"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), 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 đủ — 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.
result = solver.solve_turnstile(
website_url="https://example.com",
website_key="0x4AAAAAAA...",
proxy="http://user:pass@host:port", # optional
)
token = result["token"]await solver.solveTurnstile({
websiteURL: "https://example.com",
websiteKey: "0x4AAAAAAA...",
proxy: "http://user:[email protected]:8080",
});Xem các trang Python SDK và Node.js SDK để có danh sách đầy đủ các phương thức, hoặc tham chiếu REST API để xem vòng đời ba lệnh gọi thô.