# MCP Sunucusu

> Yerel Paymos MCP sunucusunu istemcinize ekleyin, test anahtarlarını ayrı dosyada saklayın ve entegrasyonunuzu Sandbox'ta deneyin.

`@paymos/mcp`, kodlama ajanına Sandbox faturaları ve geliştirici belgeleri sunan yerel MCP sunucusudur. stdio üzerinden çalışır; dinleme portu açmaz. Ajanın kullandığı araçları ve dönen sonuçları istemcinizden inceleyebilirsiniz.

## Gereksinimler

Node.js 20 veya daha yeni bir sürüm gerekir. [API anahtarları](/tr/docs/api-keys.md) bölümünden `pk_test_` kimliğiyle `sk_test_` gizli anahtarını hazırlayın.

## İstemciyi bağlayın

Terminalde çalıştırın:

```sh
npx -y @paymos/mcp setup
```

Kurulum istemciyi sorar. Test anahtarlarını gizli giriş alanlarına yazın; webhook imzası doğrulayacaksanız webhook gizli anahtarını da ekleyin. Terminalden seçim yapmak yerine istemciyi doğrudan belirtebilirsiniz:

```sh
npx -y @paymos/mcp setup --client codex
npx -y @paymos/mcp setup --client kimi
npx -y @paymos/mcp setup --client opencode
```

`--client` seçenekleri: `codex`, `claude-code`, `claude-desktop`, `kimi`, `cursor`, `windsurf`, `opencode`, `vscode`, `generic`. Cline, Roo Code veya özel istemcide, MCP ayarlarından gerçek dosya yolunu bulun. `generic` bu yolu zorunlu tutar:

```sh
npx -y @paymos/mcp setup --client generic --config /path/to/mcp.json
```

Varsayılan yol yerine `--config PATH` kullanabilirsiniz. Kimi CLI için varsayılan dosya `~/.kimi-code/mcp.json`; `KIMI_CODE_HOME` tanımlıysa onun altındaki `mcp.json` kullanılır. `--credentials-file PATH`, anahtar dosyasının yerini seçer. Yazılacak değişiklikleri önce görmek için `--dry-run`, seçeneklerin tamamı için `--help` ekleyin. Önizleme dosya yazmaz ve gizli anahtarları göstermez.

Anahtarlar, `XDG_CONFIG_HOME` tanımlıysa onun altında `paymos/mcp/credentials.json` dosyasına, aksi halde `~/.config/paymos/mcp/credentials.json` dosyasına kaydedilir. İstemci ayarında yalnızca `PAYMOS_CREDENTIALS_FILE` yolu bulunur. Bu dosyayı kaynak koduna eklemeyin. Otomasyonda test çiftini `PAYMOS_API_KEY_ID` ve `PAYMOS_API_SECRET` ortam değişkenleriyle verebilirsiniz; `PAYMOS_WEBHOOK_SECRET` isteğe bağlıdır. Etkileşimli terminal yoksa eksik bilgiler sorulmaz, işlem hatayla durur.

Mevcut sunucular, yorumlar ve model ayarları korunur. Aynı anahtarlarla tekrar çalıştırmak ikinci kayıt oluşturmaz. Başka bir Paymos kaydı veya farklı anahtarlar içeren dosya varsa kurulum üzerine yazmayı reddeder. Önce belirtilen dosyayı kontrol edin; başka istemciye ait dosyayı değiştirmek yerine doğru yolu seçin. Kurulum tamamlanınca istemciyi yeniden başlatın veya MCP bağlantısını yenileyin.


Dosya seçimini istemcinin açık olduğu çalışma ortamına göre yapın. VS Code kurulumu, bulunduğunuz klasördeki `.vscode/mcp.json` dosyasını kullanır; anahtarlar proje dışında kalır. Claude Code için varsayılan dosya `~/.claude.json`, Cursor için `~/.cursor/mcp.json`, Windsurf için `~/.codeium/windsurf/mcp_config.json` olur. Claude Desktop'ta macOS ve Windows yolları otomatik seçilir; diğer işletim sistemlerinde `--config` gerekir. Aynı istemcinin farklı ayar dosyalarını kullanıyorsanız, başarılı kurulumdan sonra istemcinin gerçekten hangi dosyayı okuduğunu da kontrol edin. Bu kontrol, doğru dosyaya yazılmış bir kaydın başka oturumda görünmemesini açıklayabilir.
**Model seçimi bağlantıdan ayrıdır**

MCP bağlantısını istemci yönetir. Codex, Kimi CLI veya OpenCode'da kullandığınız modelin ayrıca araç çağrılarını desteklemesi gerekir. Claude Code'u GLM ile ya da başka bir istemciyi özel modelle kullanıyorsanız da bu ayrım geçerlidir. `setup`, modelinizi veya model API uç noktasını değiştirmez; her modelin araçları kullanacağını garanti etmez.

Araçlar görünmüyorsa önce istemcinin MCP ayarlarında `paymos` bağlantısını kontrol edin. Başlatma hatasında Node.js sürümünü, `npx` erişimini ve anahtar dosyasının yolunu inceleyin. Araçlar listeleniyor fakat model çağırmıyorsa istemcinin model ve araç çağrısı ayarlarına bakın.

## Elle yapılandırma

Kurulumu kullanamıyorsanız anahtarları ayrı JSON dosyasında tutun:

```json
{"apiKeyId":"pk_test_…","apiSecret":"sk_test_…","webhookSecret":"whsec_…"}
```

`webhookSecret` isteğe bağlıdır. Unix'te dosyayı oluşturduktan sonra erişimi sınırlandırın; grup veya diğer kullanıcılar dosyayı okuyabiliyorsa sunucu dosyayı reddeder:

```sh
chmod 600 /absolute/path/credentials.json
```

Windows'ta kullanıcı dizininin mevcut ACL izinleri geçerlidir.

### mcpServers kullanan istemciler

Standart `mcpServers` biçimi şöyledir; örnek yolu kendi mutlak yolunuzla değiştirin:

```json
{
  "mcpServers": {
    "paymos": {
      "command": "npx",
      "args": ["-y", "@paymos/mcp"],
      "env": {"PAYMOS_CREDENTIALS_FILE": "/absolute/path/credentials.json"}
    }
  }
}
```

### Codex

Codex, `~/.codex/config.toml` veya `CODEX_HOME` altındaki `config.toml` dosyasında TOML kullanır:

```toml
[mcp_servers.paymos]
command = "npx"
args = ["-y", "@paymos/mcp"]

[mcp_servers.paymos.env]
PAYMOS_CREDENTIALS_FILE = "/absolute/path/credentials.json"
```

### OpenCode

OpenCode yapılandırmasında kayıt `mcp` altındadır:

```json
{
  "mcp": {
    "paymos": {
      "type": "local",
      "command": ["npx", "-y", "@paymos/mcp"],
      "environment": {"PAYMOS_CREDENTIALS_FILE": "/absolute/path/credentials.json"},
      "enabled": true
    }
  }
}
```

### VS Code

VS Code'un `.vscode/mcp.json` dosyasında `mcpServers` yerine `servers` yazın ve `paymos` kaydına `"type": "stdio"` ekleyin.

### Zed

Zed için otomatik kurulum yoktur; `context_servers` biçimini kullanarak elle ekleyin. Unix genel ayarları `~/.config/zed/settings.json`, proje ayarları `.zed/settings.json` dosyasındadır. Windows'ta Zed ayarlarından gerçek `settings.json` dosyasını açın.

### Windows başlatıcısı

Windows'ta başlatıcı `"command": "cmd"`, argümanlar `["/d", "/c", "npx", "-y", "@paymos/mcp"]` olur. Anahtar dosyasının yolunu yine `env` içinde verin.

Eski ortam değişkenleri ve `--api-key-id` / `--api-secret` bayrakları çalışır; öncelik ortam değişkenleri, bayraklar, ardından anahtar dosyasıdır.

## Araçlar ve belge kaynakları

| Araç | İşlev |
|---|---|
| `create_invoice` | Sandbox faturası oluşturur; `external_order_id` ile idempotent çalışır, `payment_url` döndürür |
| `get_invoice` | Fatura durumunu okur |
| `list_invoices` | Filtre ve imleçle faturaları listeler |
| `cancel_invoice` | Ödenmemiş faturayı gerekçesiyle iptal eder |
| `simulate_invoice_payment` | `paid`, `overpaid`, `underpay`, `cancel`, `paid_late` aşamalarını simüle eder |
| `verify_webhook_signature` | `X-Webhook-Signature` değerini yerelde doğrular |

Beş belge kaynağı da oturumdan okunabilir: `paymos://docs/quick-start`, `paymos://docs/hosted-checkout`, `paymos://docs/webhooks`, `paymos://docs/testing-sandbox`, `paymos://docs/server-sdks`.

## Sandbox sınırı

Canlı ve ödeme çıkışı anahtarları reddedilir. MCP ile entegrasyonu test edin; üretimde kendi uygulamanızın [sunucu SDK'sını](/tr/docs/server-sdks.md) kullanın. Barındırılan MCP ikinci faza ertelenmiştir; şu anda kullanılabilir değildir ve yayımlanma takvimi yoktur.

## Sonraki adımlar

[Sandbox testi](/tr/docs/testing.md), [webhook belgeleri](/tr/docs/webhooks.md) ve [hızlı başlangıç](/tr/docs/quick-start.md) sonraki adımları açıklar.