MCP
Aynı API anahtarı, bir yapay zeka ajanına izin verilen her yöntem için türlü bir araç olarak sunulur.
Xuda, /cpi yanında /mcp adresinde bir Model Context Protocol sunucusu çalıştırır. MCP destekli bir
ajanı ona oturum açarak ya da bir API anahtarıyla bağladığınızda, o anahtarın çağırmasına izin verilen her
yöntem türlü bir araç olarak görünür; yapay zeka ajanları için yazılacak ayrı bir entegrasyon yoktur.
Bağlanma
İki giriş yolu vardır ve ikisi de aynı yere varır: bir API anahtarının hakları.
Oturum açma (Claude bağlayıcıları ve diğer OAuth istemcileri)
https://xuda.ai/mcp adresini Claude'da özel bir bağlayıcı olarak ekleyin (Ayarlar, Bağlayıcılar,
Özel bağlayıcı ekle), OAuth istemci kimliğini ve sırrını boş bırakın ve Bağlan'a basın. Claude
Xuda'yı açar: zaten açık değilse oturum açın; panelde bir pencere, bağlantının API anahtarlarınızdan hangisi
adına çalışacağını sorar; birini seçin ve Bağlan'a basın. Web'deki Claude, Masaüstü, mobil ve Cowork bu
bağlantıyı paylaşır ve başka bir Claude hesabı da aynı şekilde ekler. Panelin Geliştiriciler, MCP
sekmesi yapıştırılacak adresi, bu adımları ve aşağıdaki her şeyi gösterir.
Claude Code, sunucuyu başlık olmadan eklediğinizde aynı şekilde oturum açar; ardından /mcp çalıştırın ve
Authenticate'i seçin:
Bağlantının hiçbir zaman kendi hakları yoktur. Her araç çağrısı seçtiğiniz anahtar olarak çalışır; bu yüzden anahtarın erişim modu, izin listesi ve geri alınması bağlantının da olur: anahtarı Geliştiriciler, API anahtarları altında geri alın ve bağlantı durur, bir sonraki oturum açmada başka bir anahtar istenir. Sayfa yalnızca kendi etkin anahtarlarınızı listeler; hiç yoksa önce bir tane oluşturun.
MCP istemcisi geliştiricileri için, sunucu MCP yetkilendirme belirtimini izler:
Kullanılabilir bir belirteç olmadan /mcp adresine yapılan bir çağrı, WWW-Authenticate: Bearer resource_metadata="..." ile 401 yanıtı verir; bir istemci geri kalanını bu şekilde bulur. Erişim
belirteçleri bir saat, yenileme belirteçleri 90 gün geçerlidir ve her kullanımda değiştirilir. Bir geri
döngü yönlendirme URI'si (http://localhost veya http://127.0.0.1) her bağlantı noktasıyla eşleşir.
Başlıkta bir API anahtarı
Anahtar, /cpi üzerinde api_key olarak kullanacağınız aynı anahtardır ve bir Authorization: Bearer
başlığına konur. Ayrı bir MCP kimlik bilgisi yoktur. Authorization başlığı olmayan bir istek ya da etkin
bir xuda_api_keys belgesine çözümlenmeyen bir anahtar, hiçbir araç kaydedilmeden 401 ile reddedilir.
Oturumlar
Aktarım akış destekli HTTP'dir: ilk istek, bir oturum açan ve mcp-session-id başlığı döndüren bir MCP
initialize çağrısıdır; o bağlantıdaki sonraki her istek aynı başlığı ve aynı kimlik bilgisini taşır. Bir
oturum, 10 dakika istek gelmezse kapanır. Kapanmış bir oturumdaki istek 404 yanıtı alır ve bir MCP
istemcisi bunun üzerine kendiliğinden yeni bir oturum başlatır.
Neler araç olur
Araçlar, oturumun başında anahtarın zaten sahip olduğu erişim modundan kaydedilir:
- Tam erişim: katalogdaki
privateolmayan her yöntem bir araç olarak kaydedilir ve bağlanma anında çözülür; bu yüzden anahtar oluşturulduktan sonra eklenen bir yöntem, anahtarın kendisinde hiçbir değişiklik olmadan kullanılabilir. - Özel erişim: yalnızca anahtarın izin listesindeki yöntemler kaydedilir.
Çalışan bir oturum anahtarını takip eder: anahtara her dakika, arkasındaki modüllere ve eklentilere ise her
beş dakikada bir bakar; araç kümesi değiştiğinde notifications/tools/list_changed gönderir. Dinleyen bir
istemci (Claude dinler) yeni listeyi yeniden bağlanmadan okur; böylece anahtarda izin verdiğiniz bir yöntem,
zaten bağlı olan bir ajana ulaşır.
Her araç yöntemin kendi biçimini korur: araç adı yöntem adıdır (get_account_projects, dbs_read, ...),
başlığı yöntem adının Başlık Biçimi hâlidir, açıklaması yöntemin kendi description değeridir ve girdi
şeması yöntemin fields alanlarından alan alan oluşturulur; zorunlu alanlar zorunlu kalır, geri kalan her
şey isteğe bağlıdır. Tanınan bir türü olmayan bir alan, tüm oturumu bozmak yerine yine de serbest bir araç
bağımsız değişkeni olur; böylece tuhaf tanımlanmış tek bir yöntem kataloğun geri kalanını asla aşağı çekmez.
Bir Tam Yığın VPS'e kapsamlanmış bir anahtar, yukarıdaki ekosistem yöntemlerinin yanında o makinenin yüklü eklenti araçlarını da sunar; böylece bir ajan, hem platforma hem de geliştiricinin makinede oluşturduğu şeye tek oturumda ulaşabilir. Bkz. Tam Yığın VPS.
Bir aracı çağırma
Bir ajan bir aracı, yöntemin alanlarının tarif ettiği aynı bağımsız değişkenlerle çağırır. Xuda, yöntemi
/cpi/<method> gibi dahili olarak çağırarak yanıtlar ve yöntemin {code, data} zarfını araca metin olarak
geri verir. Başarısız bir çağrı MCP katmanında yine normal döner; -1 ve üstü kod, düz bir REST çağrısında
olduğu gibi araç sonucunda görünür, böylece bir ajan onu kendi hata işlemenizin okuyacağı şekilde okur.
Bkz. Hatalar.
Herhangi bir araç çalışmadan önce başarısız olan bir istek (eksik veya reddedilen bir kimlik bilgisi
(401), kapanmış bir oturum (404, kod -32001), bozuk bir MCP iletisi) bir araç sonucu yerine bir
JSON-RPC hatası olarak döner: