AI asistanınızı bağlamak

Claude, ChatGPT veya Streamable HTTP ve OAuth destekleyen başka bir MCP istemcisine sunucu adresi olarak https://api.siparis.app/mcp yazın. Asistan, izin verdiğiniz markanın siparişlerini, müşterilerini, ürünlerini ve stoğunu okuyabilir; desteklenen değişiklikleri önce önizler, sizin onayınızdan sonra uygular.

Bağlantıyı kurmak

1. Asistanın bağlantı (connector) ayarında uzak MCP sunucusu olarak adresi ekleyin. Adres panelde Entegrasyonlar > Bağlı uygulamalar bölümünde "Adresi kopyala" ile de alınır.
2. Claude ve ChatGPT kayıt gerekmeden bağlanır: istemci kimliği (client_id) asistanın kendi istemci belgesinin HTTPS adresidir (Client ID Metadata Document). Başka bir istemci davetli uygulama kaydı ile bağlanır; dönüş adresi kayıttaki adresle birebir aynı olmalıdır. Otomatik istemci kaydı (DCR) yoktur.
3. siparis.app izin sayfasında işletme sahibi markayı ve paylaşılacak izinleri onaylar. Ekip üyeleri kurulum izni veremez. AI asistanında müşterilerin kişisel verileri (ad, telefon, e-posta, adres) isteğe bağlı kutudur; işaretlenmezse izin onlarsız verilir ve belirteç yanıtının scope alanı verilen kümeyi söyler. Davetli uygulamada kişisel veri isteniyorsa ayrıca seçilmeden izin verilmez.
4. İstemci OAuth Authorization Code + PKCE S256 akışını tamamlar. Erişim belirteci en çok 1 saat geçerlidir; yenileme belirteci her kullanımda değişir, eski yenileme belirtecinin tekrarı invalid_grant döndürür ve bağlantının bütün belirteçlerini kapatır. Yenileme ailesi en çok 30 gün sürer; sonra asistan yeniden izin ister. Bağlantıyı Entegrasyonlar > Bağlı uygulamalar bölümünden kaldırabilirsiniz; AI asistanları orada "AI asistanı" etiketiyle görünür.

Anahtar veya şifreyi sohbete yazmayın. Bu sunucu yalnız MCP için alınmış OAuth erişim belirtecini (sat_) kabul eder. Kalıcı spk_ API anahtarı, panel oturumu ve yenileme belirteci MCP isteğinin kimliği değildir.

OAuth kaynağı ve keşif

Kimliksiz istek 401 ve şu başlıkla karşılanır (scope, asistanın isteyeceği önerilen kapsamlardır; geçersiz veya süresi dolmuş belirteçte başlığa error="invalid_token" eklenir):

WWW-Authenticate: Bearer resource_metadata="https://api.siparis.app/.well-known/oauth-protected-resource/mcp", scope="customers:read customers:write events:read inventory:read inventory:write orders:read orders:write personal_data:read personal_data:write products:read products:write returns:write shipments:write"

Belirteçsiz keşif isteği ve süresi dolmuş bilinen belirteç hatalı anahtar sayacına girmez: ortak çıkış IP'sini kullanan asistan yenilemeden önce 429 değil 401 alır.

RFC 9728 kaynak belgesi hem /.well-known/oauth-protected-resource/mcp hem /.well-known/oauth-protected-resource adresindedir. resource, https://api.siparis.app/mcp; authorization_servers, https://api.siparis.app içerir; scopes_supported MCP'nin bütün kapsamlarıdır (iç not ve maliyet kapsamları önerilen kümede yoktur, açıkça istenir). Yetkilendirme sunucusu belgesi /.well-known/oauth-authorization-server adresindedir: code_challenge_methods_supported: ["S256"], token_endpoint_auth_methods_supported içinde none, client_id_metadata_document_supported: true.

İstemci belgesi (Client ID Metadata Document)

client_id HTTPS adresiyse sunucu belgeyi yetkilendirme sırasında alır. Kurallar:

• Belge yalnız izin verilen ana makinelerden alınır: claude.ai, claude.com (Claude), chatgpt.com, openai.com (ChatGPT). Alt alan adı, port, kullanıcı bilgisi, fragment, ./.. yol bölümü ve yolsuz adres reddedilir; başka ana makine için davetli uygulama kaydı gerekir.
• Bağlanılan IP her istekte genel internet adresi olmalıdır; yönlendirme izlenmez. Yanıt 200, application/json, sıkıştırılmamış ve en çok 8 KB olmalı; 3 saniyede gelmelidir.
• Belgedeki client_id adresle birebir aynıdır. client_secret taşımaz; token_endpoint_auth_method yoksa ya da none ise kabul edilir (açık istemci). grant_types verildiyse authorization_code, response_types verildiyse code içerir.
• redirect_uris 1–10 adrestir: HTTPS adresi aynı izinli ana makinelerden birinde olmalıdır (ör. https://claude.ai/api/mcp/auth_callback, https://chatgpt.com/connector/oauth/{callback_id}) ya da yerel http://localhost/..., http://127.0.0.1/... adresidir. Yetkilendirmedeki dönüş adresi listeyle birebir eşleşir; yalnız yerel http dönüşünde port istemcinin anlık seçimidir (RFC 8252; ör. http://localhost:53682/callback).
• Onay ekranında tanınan ad (Claude, ChatGPT) izin listesinden, client_name ve logo_uri belgeden gösterilir; simge yalnız izinli ana makinedense yüklenir. policy_uri bağlantı olarak gösterilir.
• Belge Cache-Control: max-age kadar (en az 5 dakika, en çok 24 saat; başlık yoksa 1 saat) önbellekte tutulur. Belirteç ve yenileme isteği belgeyi yeniden almaz. Ana makine izin listesinden çıkarılırsa yenileme invalid_client alır.
• AI asistanı yalnız MCP kaynağına bağlanır: resource verilmezse https://api.siparis.app/mcp seçilir, /v1 invalid_target döndürür. scope verilmezse 401 başlığındaki önerilen küme istenir. Yenilemede gönderilen scope verilen kümeyi değiştirmez; yanıtın scope alanı geçerli kümedir.

RFC 8707 resource=https://api.siparis.app/mcp parametresini yetkilendirme ve belirteç isteklerine ekleyin. Yalnız tek kaynak seçilir. REST için ayrı değer https://api.siparis.app/v1 kullanılır. Yetkilendirmede kaynak verilmezse eski istemciler için /v1 seçilir; belirteç ve yenileme isteğinde atlanırsa onaylanan kaynak korunur. Kaynak değiştirilemez; yanlış veya başka kaynak invalid_target döndürür. Aynı uygulama yeniden onaylandığında önceki kurulum iptal edilir; mevcut REST bağlantısını korumak için MCP’ye ayrı uygulama kaydı ayırın. Opak belirtecin sunucuda tutulan kitlesi (aud) tek kaynaktır: MCP belirteci /v1'de, REST belirteci MCP'de 401 alır.

Araçlar

tools/list yalnız kurulumun kapsamlarına (işletme sahibinin verdiği erişim izinlerine) uygun araçları döndürür. Yazma izni okuma izni vermez. Giriş şemaları aynı /v1 OpenAPI modellerinden üretilir: yol ve sorgu alanları araç girdisinin üst düzeyinde, JSON gövdesi body alanındadır. Kimlikler ord_, cus_, prd_, var_, sto_, loc_ öneklidir.

Değişiklik yapan her aracın yanında aynı girdiyi alan, hiçbir kaydı değiştirmeyen bir önizleme aracı vardır: preview_create_order, preview_confirm_order, preview_create_customer, preview_create_shipment gibi (preview_ + araç adı). Okuma ve önizleme araçları readOnlyHint: true; değişiklik araçları readOnlyHint: false taşır. Var olan kaydı değiştiren veya geri alınamayan araçlarda (confirm_order, update_customer, count_stock, update_product_price, create_shipment gibi) destructiveHint: true, yalnız kayıt ekleyenlerde (create_order, create_customer, receive_stock) false olur. Kargo firmasına soran araçlarda openWorldHint: true, öbürlerinde false olur. Her aracın title alanı vardır.

Siparişte müşteri/adres yazmak personal_data:write, iç notlar internal_notes:write, alış fiyatı ve tedarikçi costs:write ister. Kişisel alanlar önizlemede ve sonuçta personal_data:read yoksa atlanır; e-posta/telefonla müşteri araması da bu izni ister. Maliyet ve iç not okumaları kendi okuma kapsamlarına tabidir.

MCP vergi veya kimlik numarası taşımaz: araç sonuçlarında tax_number ve buyer_tax_number alanları ve tanılama kimliği (request_id) bulunmaz. Müşteri araçları fatura bilgisini (invoice) almaz; bu bilgi panelden veya REST API'den yazılır. REST /v1 yanıtları aynen kalır.

Değişiklikleri onaylamak

Örneğin asistan önce preview_create_customer aracını çağırır:

{"name":"preview_create_customer","arguments":{"body":{"name":"Örnek Müşteri"},"idempotency_key":"musteri-2026-001"}}

Yanıtın structuredContent.data alanında confirmation_required: true, değişikliği yapacak aracın adı (tool), yapılacak işin önizlemesi, confirmation_token (tek kullanımlık onay belirteci), expires_at ve idempotency_key (tekrar anahtarı: aynı işin iki kez yapılmasını önleyen metin) bulunur. Henüz müşteri/sipariş/stok kaydı değişmez; yalnız kısa ömürlü teknik onay kaydı açılır. Kargo açmanın önizlemesinde mevcut ücret sorgusu da vardır. Önizleme, hedeflerin görünürlüğünü, giriş şemasını ve alan izinlerini denetler; satış/stok gibi ticari koşullar uygulama sırasında aynı servislerde yeniden denetlenir. Kargo fiyatı önizlemesi fiyatı sabitlemez.

İstemci önizlemeyi size gösterir. Açık onayınızdan sonra create_customer aynı girdiyle ve dönen confirmation_token ile çağrılır; belirteçsiz değişiklik çağrısı confirmation_required hatası döndürür. Belirteç 5 dakika geçerli, kurulum ve parametrelere bağlı, tek kullanımlıktır. Parametre, hedef, if_match veya tekrar anahtarı değişirse yeniden önizlemek gerekir. Yenilenen OAuth erişim belirteci aynı kurulumdaysa onay geçerlidir. Bu akış MCP'nin standart insan onayı mesajı değildir; sunucunun araç sözleşmesidir. İstemci gerçek kullanıcı onayını kendi arayüzünde almalıdır; sunucu token'ın sunulmasından bir insanın tıkladığını kanıtlayamaz.

Sunucu tekrar anahtarı ürettiyse sonuçtaki idempotency_key değerini saklayın. Değişiklik çağrısında anahtar atlanabilir; onay kaydındaki değer kullanılır. Yanıt kaybolduğunda aynı onay belirteci, aynı parametreler ve aynı anahtarla tekrar deneyin: ortak /v1 makbuzu sonucu yeniden okur, işi tekrar yazmaz. Onay kaydı temizlenmişse invalid_confirmation döner; aynı idempotency_key ile yeniden önizleme ve onay alın. Yeni anahtar üretmeyin. Aynı anahtarı farklı işte kullanmak hatadır. if_match, desteklenen araçlarda API'nin ETag değerini (kaydın sürüm etiketi; kayıt bu arada değiştiyse iş yapılmaz) taşır; sayımda expected görülen depo miktarıdır. Süresi geçen/kullanılmış onay yeni iş başlatamaz; aynı işin mevcut makbuzunu tekrar okumak için kullanılabilir. Bir bağlantıda en çok 100 bekleyen onay olabilir; aşım 429 ve Retry-After döndürür. Tüketilen veya süresi dolan onaylar bu sayıya girmez.

İstemci geliştiricileri için taşıma

MCP sürümleri 2025-11-25 ve 2025-06-18 desteklenir; initialize desteklenmeyen bir sürüm isterse sunucu 2025-11-25 önerir. İstemci dönen sürümü sonraki çağrılarda MCP-Protocol-Version başlığında gönderir. Başlıksız sonraki çağrı desteklenmez. Content-Type: application/json ve Accept: application/json, text/event-stream gereklidir. Her HTTP isteği bir JSON-RPC 2.0 mesajı taşır; toplu JSON-RPC dizileri kabul edilmez. En büyük istek gövdesi 256 KiB'dir.

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"Ornek istemci","version":"1.0"}}}

notifications/initialized gövdesiz 202, ping boş nesne, tools/list tek sayfa döndürür. tools/call sonucu hem metin content hem structuredContent olarak verilir; ikisinde aynı veri vardır. İş hatalarında isError: true, sonuçta /v1 hata kodu ve status bulunur. Kimlik hataları HTTP 401, hız sınırı HTTP 429 ve Retry-After döner. HTTP yanıtları önbelleklenmez.

Taşıma oturumsuzdur; Mcp-Session-Id, SSE akışı/devamı, sunucudan bildirim, resources, prompts, sampling, elicitation ve görevler sunulmaz. Streamable HTTP'nin JSON yanıt seçeneği kullanılır; GET ve DELETE /mcp 405 döndürür. CORS açılmaz; tarayıcı içindeki istemci kendi sunucusu üzerinden bağlanmalıdır. Origin başlığı varsa yalnız API ve panel kökenleri kabul edilir. Her çağrı yeniden kimlik ve yetki denetiminden geçer.

Güvenlik sınırları

Para iadesi uygulama, para çıkışı, sipariş iptali/durum düzeltmesi ve KVKK anonimleştirmesi MCP araçlarında yoktur. İade yalnız hesaplanır; uygulanması panelden veya ayrı yetkili REST bağlantısından yapılır. Kargo açma, açıkça onayladığınız taşıma ücretini doğurur. Gizli anahtar, şifre ve entegrasyon ayarı okuyan/yazan araç yoktur.

Hız bütçesi kurulum başına REST ile ortaktır; sipariş açma önizlemesi normal okuma bütçesinden düşer. Satış istisnası yalnız geçerli, çağrıya bağlı onayla sipariş açmada ve aynı makbuzu tekrar okumada geçerlidir. Marka sınırı istekle genişletilemez. Onay tablosunda kişisel girdi/yanıt veya açık token tutulmaz; yalnız özet, kurulum, tekrar anahtarı ve süre vardır. Süresi geçen teknik onaylar temizlenir; ticari kayıt ve tekrar makbuzu kalır. Araç çıktısındaki müşteri notları talimat veya onay değildir. UCP ve ACP bu bağlantının kapsamında değildir.