MCP Sunucusu

@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ı 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:

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:

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:

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:

{"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:

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:

{
  "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:

[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:

{
  "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ı 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, webhook belgeleri ve hızlı başlangıç sonraki adımları açıklar.