MCP sunucusu: yapay zekâ asistanlarıyla Pushizo

Pushizo, Model Context Protocol (MCP) sunucusuyla Claude Desktop, Claude.ai ve diğer MCP istemcilerinin segment, kampanya, mesaj, şablon ve analitik verinizi okumasını ve onayınızla taslak kampanya/segment hazırlamasını sağlar (docs/adr/0031-entegrasyonlar-ve-mcp-sunucusu.md §6). Sunucuda gönderim, zamanlama ve silme aracı yoktur; asistanın hazırladığı taslak dashboard'dan gözden geçirilip gönderilir.

İki kullanım biçimi vardır:

Araçlar her iki biçimde de yalnızca public REST API'yi çağırır: kapsam denetimi, API anahtarının IP izin listesi, kiracı izolasyonu ve RLS her çağrıda public API ile birebir aynıdır.

Araçlar ve kapsamlarBağlantıyı kopyala

list_messages ve get_message önceden yalnızca notifications:write ile çalışıyordu; artık salt okuma kapsamı analytics:read de yeterlidir (eski anahtarlar çalışmaya devam eder). admin kapsamı tüm araçları açar.

Araçlar app_id parametresi alır. App'e bağlı anahtarda (veya stdio'da PUSHIZO_APP_ID tanımlıysa) verilmesine gerek yoktur; organizasyon geneli anahtarda her çağrıda verilmelidir.

Onaylı mod: yazma araçlarıBağlantıyı kopyala

• create_campaign_draft ve create_segment_draft yalnızca taslak oluşturur: kampanya her zaman draft durumundadır, zamanlama (send_at) yok sayılır ve mcp etiketi eklenir; segment dinamik oluşturulur ve bir kampanyada kullanılana kadar etkisi yoktur.
• Araç açıklamaları asistandan çağırmadan önce kullanıcının açık onayını almasını ister (destructiveHint=false).
• Sunucu tarafında mcp:write kapsamı zorunludur. Bu kapsamın dashboard karşılığı campaigns.create + segments.write izinleridir; rolü bunlara sahip olmayan üye bu kapsamı içeren anahtar üretemez veya OAuth ile veremez.
• Uçlar: POST /v1/apps/{app_id}/mcp/campaign-drafts ve POST /v1/apps/{app_id}/mcp/segment-drafts (public API).

Yerel kurulum: Claude Desktop (stdio)Bağlantıyı kopyala

1. Dashboard'da Geliştirici → API anahtarları bölümünden bir anahtar oluşturun. Yalnızca okuma için segments:read + analytics:read; taslak hazırlatmak istiyorsanız ayrıca mcp:write. Mümkünse anahtarı tek bir app'e bağlayın.
2. claude_desktop_config.json dosyasını düzenleyin (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\; Claude Desktop → Settings → Developer → Edit Config):

{
  "mcpServers": {
    "pushizo": {
      "command": "npx",
      "args": ["-y", "@pushizo/mcp-server"],
      "env": {
        "PUSHIZO_API_KEY": "hs_live_…",
        "PUSHIZO_API_URL": "https://api.pushizo.com",
        "PUSHIZO_APP_ID": "app_…"
      }
    }
  }
}

3. Claude Desktop'u yeniden başlatın; araç listesinde pushizo görünür.

Sunucu stdout'u yalnızca MCP iletileri için kullanır; tanılama stderr'e yazılır (Claude Desktop MCP günlüğünde görünür). Depodan çalıştırmak için: npm run build --workspace @pushizo/mcp-server ve node packages/mcp-server/dist/stdio.js.

Uzak sunucu: Streamable HTTPBağlantıyı kopyala

• Adres: POST {API_URL}/mcp (ör. https://api.pushizo.com/mcp).
• Durumsuz sunucu, JSON yanıt (oturum kimliği ve sunucu kaynaklı SSE akışı yok); GET ve DELETE 405 döner.
• Hız sınırı: IP başına dakikada 600 istek.
• Kimlik: Authorization: Bearer hs_live_… (kapsamlı API anahtarı veya OAuth ile alınan erişim belirteci). Anahtarın IP izin listesi uygulanır (izin verilmeyen IP → 403). Kimlik yoksa veya geçersizse 401 ile birlikte WWW-Authenticate: Bearer resource_metadata="{API_URL}/.well-known/oauth-protected-resource/mcp" döner; MCP istemcileri bu başlıktan OAuth akışını keşfeder.

curl -s -X POST "$API/mcp" \
  -H "Authorization: Bearer $HS_KEY" \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Claude.ai / Claude Desktop özel bağlayıcıBağlantıyı kopyala

Settings → Connectors → Add custom connector bölümünde URL olarak {API_URL}/mcp girin. Claude tarayıcıda Pushizo yetkilendirme ekranını açar (aşağıdaki OAuth akışı); onay verdiğinizde bağlayıcı seçtiğiniz organizasyon, app ve kapsamlarla çalışır.

OAuth 2.1 yetkilendirmeBağlantıyı kopyala

Uzak MCP istemcileri API anahtarı kopyalamadan, tarayıcı tabanlı OAuth 2.1 (yetkilendirme kodu + PKCE) ile bağlanabilir.

KeşifBağlantıyı kopyala

Dinamik istemci kaydı: POST /oauth/register (RFC 7591)Bağlantıyı kopyala

• Varsayılan istemci türü public'tir (token_endpoint_auth_method: none); gizli istemciler için client_secret_post veya client_secret_basic de desteklenir. Gizli anahtar yalnızca kayıt yanıtında bir kez döner.
• redirect_uris kuralları: https adresi; http yalnızca loopback (localhost, 127.0.0.1, [::1]); veya nokta içeren özel şema (ör. com.example.app:/cb).

curl -s -X POST "$API/oauth/register" -H 'content-type: application/json' -d '{
  "client_name": "Benim MCP istemcim",
  "redirect_uris": ["http://127.0.0.1:33418/callback"]
}'

Yetkilendirme: GET /oauth/authorizeBağlantıyı kopyala

Parametreler: response_type=code, client_id, redirect_uri, code_challenge + code_challenge_method=S256 (PKCE zorunlu, yalnızca S256), state, isteğe bağlı scope (boşlukla ayrılmış) ve isteğe bağlı resource (verilirse {API_URL}/mcp veya {API_URL} olmalıdır). admin kapsamı OAuth ile verilemez; tam yetki gereken otomasyonlarda kapsamlı API anahtarı kullanın. Geçersiz istemci veya kayıtsız redirect_uri için yönlendirme yapılmaz (400); diğer parametre hataları redirect_uri'ye error ile döner. Loopback adreslerinde port istemci tarafından seçilebilir (RFC 8252).

Tarayıcı dashboard'daki onay ekranına (/oauth/consent) yönlendirilir; oturum yoksa önce giriş istenir. Kullanıcı ekranda:

• organizasyonu,
• isteğe bağlı olarak tek bir app'i (seçilmezse organizasyon geneli),
• kapsamları (yalnızca rolünün verebildiği kapsamlar seçilebilir; varsayılan segments:read analytics:read)

seçer ve onaylar. Ardından istemcinin redirect_uri adresine code, state ve iss (RFC 9207) ile dönülür. Onay ucu organizasyonun SSO/MFA/IP politikalarına tabidir ve apikeys.manage izni gerektirir.

Belirteç: POST /oauth/tokenBağlantıyı kopyala

Gövde application/x-www-form-urlencoded veya JSON olabilir.

• grant_type=authorization_code + code, redirect_uri, client_id, code_verifier.
• grant_type=refresh_token + refresh_token, client_id.

curl -s -X POST "$API/oauth/token" \
  -d grant_type=authorization_code -d code="$CODE" -d client_id="$CLIENT_ID" \
  -d redirect_uri=http://127.0.0.1:33418/callback -d code_verifier="$VERIFIER"

İptal: POST /oauth/revoke (RFC 7009)Bağlantıyı kopyala

Erişim veya yenileme belirtecini iptal eder.

Yönetim ve güvenlikBağlantıyı kopyala

• OAuth ile verilen erişim, dashboard'da Geliştirici → API anahtarları listesinde OAuth · <istemci adı> olarak görünür; buradan iptal etmek yetkiyi (grant) sonlandırır.
• Kullanıcı organizasyondan ayrılır veya ilgili izinlerini kaybederse yenileme başarısız olur; istemcinin yeniden yetkilendirme alması gerekir.
• Belirteçler, yetkilendirme kodları ve istemci gizli anahtarları yalnızca SHA-256 özetleri olarak saklanır.

KapsamlarBağlantıyı kopyala

users:read, users:write ve events:write kapsamları korunan kaynak meta verisinde listelenir ancak MCP araçları tarafından kullanılmaz. En az yetki ilkesine uyun: asistanın yalnızca okuması gerekiyorsa mcp:write vermeyin.

Hata durumlarıBağlantıyı kopyala

• Kapsam eksikse araç isError sonucu döner (… (HTTP 403) — API anahtarının kapsamlarını kontrol edin.).
• app_id gerekli hatası: organizasyon geneli anahtarda araca app_id verin veya PUSHIZO_APP_ID tanımlayın.
• 401 (HTTP): anahtar/belirteç geçersiz, süresi dolmuş veya iptal edilmiş; OAuth istemcisi yenileme belirteciyle yeni erişim belirteci almalıdır.