CaptchaSonic **ajan öncelikli** tasarlanmıştır. Her AI ajanı CAPTCHA'ları **MCP sunucumuz** üzerinden çözebilir. Bunun iki kullanım yolu vardır:

- **Barındırılan:** `https://mcp.captchasonic.com` adresini API anahtarınızla birlikte bearer token olarak kullanın. Kurulum gerektirmez. Önerilen yöntemdir.
- **Yerel:** Yalnızca yerel sunucuları destekleyen istemciler için stdio üzerinden `npx -y @captchasonic/mcp-server`.

Her iki yöntem de aynı beş aracı sunar: `solve_token_captcha`, `solve_image_captcha`, `get_task_result`, `get_balance` ve `list_captcha_types`. Her istemci için [MCP Başlangıç kılavuzu](/docs/mcp/get-started) ile başlayın veya aşağıdaki ajana özel notlara bakın. Ajanınız MCP kullanamıyorsa bunun yerine [doğrudan SDK](#without-mcp-direct-sdk) ile çağrı yapın.

## Ajanlar için Altın Yol

Bunu herhangi bir ajana ekleyin; tek bir istekte CAPTCHA çözebilir:

```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]
> Bir ajanı [Ajanlar için MCP](/docs/mcp/for-agents) sayfasına yönlendirin. Bu sayfa sitekey'lerin nasıl bulunacağını, doğru aracın nasıl seçileceğini ve token'ın nasıl gönderileceğini anlatır; böylece ajan ek talimat olmadan çalışabilir.

---

## Claude Code

Barındırılan sunucuyu ekleyin:

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

Yerel çalıştırmayı tercih ederseniz `claude mcp add captchasonic --env SONIC_API_KEY=sonic_xxx -- npx -y @captchasonic/mcp-server` komutu aynı araçları stdio üzerinden sunar.

### Claude skill eklentisi (önerilen)

Yönlendirmeli iş akışları için resmi **CaptchaSonic skill eklentisini** kurun. Üç Claude skill'i içerir ve `SONIC_API_KEY` ortam değişkenini kullanarak barındırılan MCP sunucusuna bağlanır. Anahtarınızı dışa aktarın, Claude Code'u başlatın, ardından şunu çalıştırın:

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

Ardından üç skill, ajanı yaygın iş akışlarında adım adım yönlendirir:

- **`captchasonic-setup`** — ilk MCP kurulumu ve doğrulama.
- **`captchasonic-solve`** — her CAPTCHA türünü adım adım yönlendirmeyle çözme.
- **`captchasonic-balance`** — hesap bakiyesini ve kredi durumunu kontrol etme.

> [!TIP]
> Toplu çözümlerden önce `get_balance` aracını (veya `captchasonic-balance` skill'ini) bir koruma olarak kullanın; kredi azalırsa ajan erken durabilir.

---

## Antigravity

CaptchaSonic'i Antigravity'nin MCP yapılandırmasına yerel bir stdio sunucusu olarak kaydedin:

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

Antigravity'nin MCP sunucularını yeniden yükleyin; CaptchaSonic araçları ajanın araç listesinde görünür.

---

## Cursor

**Settings → MCP** bölümünü açın (veya `~/.cursor/mcp.json` dosyasını düzenleyin) ve barındırılan sunucuyu ekleyin:

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

---

## Windsurf

**Settings → Cascade → MCP Servers** bölümünü açın (veya `~/.codeium/windsurf/mcp_config.json` dosyasını düzenleyin):

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

---

## Genel MCP

Uzak sunucuları destekleyen her MCP istemcisi için: Streamable HTTP taşıma yöntemiyle `https://mcp.captchasonic.com` adresini ve `Authorization: Bearer sonic_xxx` başlığını kullanın. VS Code, Codex ve Gemini CLI yapılandırmaları [Başlangıç kılavuzunda](/docs/mcp/get-started) yer alır.

Yalnızca yerel sunucu çalıştırabilen istemciler standart stdio bloğunu kullanır (bkz. [Yerel çalıştırma](/docs/mcp/run-locally)):

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

---

## n8n

CaptchaSonic, 20'den fazla CAPTCHA türünü sürükle-bırak iş akışı düğümlerine dönüştüren **doğrulanmış bir n8n topluluk düğümüne** sahiptir ([n8n.io listesi](https://n8n.io/integrations/captchasonic/)). Hem bağımsız düğüm olarak hem de n8n AI Agent düğümü için araç olarak çalışır.

→ **[Tam n8n Entegrasyon Kılavuzu](/docs/integrations/n8n)** — adım adım kurulum, kimlik bilgisi ayarı, 4 iş akışı tarifi, CAPTCHA türüne özel yapılandırma, hata yönetimi kalıpları ve sorun giderme.

**Hızlı kurulum:** Settings → Community Nodes → `n8n-nodes-captchasonic` paketini kurun → API anahtarınızla bir CaptchaSonic kimlik bilgisi oluşturun → tamam.

---

## MCP olmadan (doğrudan SDK)

Ajanınız MCP kullanamıyorsa SDK'yı doğrudan çağırın. Token türü bir CAPTCHA tek bir fonksiyon çağrısıdır.

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

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

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

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

  </LangTabs.Tab>
</LangTabs>

Tam metot listesi için [Python SDK](/docs/clients-sdks/python) ve [Node.js SDK](/docs/clients-sdks/nodejs) sayfalarına, ham üç aşamalı yaşam döngüsü için ise [REST API başvurusuna](/docs/api) bakın.
