MCP
Ugyanaz az API-kulcs, egy AI-ügynök számára metódusonként egy típusos eszközként közzétéve.
A Xuda egy Model Context Protocol szervert futtat a /mcp címen, a /cpi mellett. Csatlakoztasson hozzá egy
MCP-t ismerő ügynököt, bejelentkezéssel vagy API-kulccsal, és minden metódus, amelyet a kulcs hívhat,
típusos eszközként jelenik meg, az AI-ügynököknek nem kell külön integrációt írni.
Csatlakozás
Két út van, és mindkettő ugyanoda vezet: egy API-kulcs jogaihoz.
Bejelentkezés (Claude-összekötők és más OAuth-kliensek)
Adja hozzá a https://xuda.ai/mcp címet egyéni összekötőként a Claude-ban (Beállítások, Összekötők,
Egyéni összekötő hozzáadása), hagyja üresen az OAuth-kliensazonosítót és a titkot, és nyomja meg a
Csatlakozás gombot. A Claude megnyitja a Xudát: jelentkezzen be, ha még nem tette, és az irányítópulton egy
ablak megkérdezi, hogy a kapcsolat az API-kulcsai közül melyik nevében cselekedjen, válasszon egyet, és
nyomja meg a Csatlakozás gombot. A webes Claude, a Desktop, a mobil és a Cowork megosztja ezt a
kapcsolatot, és bármely más Claude-fiók ugyanígy adja hozzá. Az irányítópult Fejlesztők, MCP lapja
megmutatja a beillesztendő címet, ezeket a lépéseket és az alábbi mindent.
A Claude Code ugyanígy jelentkezik be, ha a szervert fejléc nélkül adja hozzá, majd futtatja az /mcp
parancsot, és a Hitelesítés pontot választja:
A kapcsolatnak soha nincs saját joga. Minden eszközhívás a kiválasztott kulcs nevében fut, így a kulcs hozzáférési módja, engedélylistája és visszavonása a kapcsolaté is: vonja vissza a kulcsot a Fejlesztők, API-kulcsok alatt, és a kapcsolat leáll, a következő bejelentkezéskor pedig másik kulcsot kér. Az oldal csak a saját aktív kulcsait listázza, ha nincs ilyen, előbb hozzon létre egyet.
Kliensfejlesztőknek: a szerver az MCP engedélyezési specifikációját követi:
A használható token nélküli /mcp hívás 401 választ ad WWW-Authenticate: Bearer resource_metadata="..." fejléccel, így találja meg a kliens a többit. A hozzáférési tokenek egy óráig
érvényesek, a frissítő tokenek 90 napig, és minden használatkor kicserélődnek. A visszacsatolási átirányítási
URI (http://localhost vagy http://127.0.0.1) bármely porton egyezik.
API-kulcs egy fejlécben
A kulcs egy Authorization: Bearer fejlécben megy, ugyanaz a kulcs, amelyet a /cpi végponton api_key
néven használna. Külön MCP-hitelesítő adat nincs. Az Authorization fejléc nélküli kérés, vagy olyan kulcs,
amely nem old fel aktív xuda_api_keys dokumentumra, 401 választ kap, mielőtt bármilyen eszköz regisztrálva
lenne.
Munkamenetek
Az átvitel streamelhető HTTP: az első kérés egy MCP initialize hívás, amely munkamenetet nyit, és egy
mcp-session-id fejlécet ad vissza. Minden következő kérés ezen a kapcsolaton ugyanazt a fejlécet és ugyanazt
a hitelesítő adatot hordozza. A munkamenet 10 perc kérés nélkül bezárul. A bezárt munkamenetre érkező kérés
404 választ kap, az MCP-kliens pedig magától új munkamenetet indít.
Mi válik eszközzé
Az eszközök a munkamenet elején regisztrálódnak abból a hozzáférési módból, amellyel a kulcs már rendelkezik:
- Teljes hozzáférés: a katalógus minden nem
privatemetódusa eszközként regisztrálódik, a csatlakozáskor feloldva, így a kulcs létrehozása után hozzáadott metódus a kulcs módosítása nélkül elérhető. - Egyéni hozzáférés: csak a kulcs engedélylistáján lévő metódusok regisztrálódnak.
A futó munkamenet lépést tart a kulcsával: percenként ránéz a kulcsra, ötpercenként pedig a mögötte lévő
modulokra és bővítményekre, és ha az eszközök köre elmozdult, notifications/tools/list_changed üzenetet küld.
Az a kliens, amely figyel (a Claude igen), újracsatlakozás nélkül olvassa az új listát, így a kulcson
engedélyezett metódus eljut a már csatlakozott ügynökhöz.
Minden eszköz megtartja a metódus saját alakját: az eszköz neve a metódus neve (get_account_projects,
dbs_read, ...), a címe a metódus neve Title Case írásmóddal, a leírása a metódus saját description mezője,
a bemeneti sémája pedig a metódus fields mezőiből épül fel mezőnként, a kötelező mezők kötelezők maradnak,
minden más opcionális. A fel nem ismert típusú mező megengedő eszközargumentum lesz, nem töri meg az egész
munkamenetet, így egyetlen furcsán megadott metódus sem viszi magával a katalógus többi részét.
A Teljes körű VPS-re korlátozott kulcs a gép telepített bővítményeszközeit is megjeleníti a fenti ökoszisztéma-metódusok mellett, így az ügynök egyetlen munkamenetben eléri a platformot és azt is, amit a fejlesztő a gépre épített. Lásd a Teljes körű VPS oldalt.
Eszköz hívása
Az ügynök az eszközt ugyanazokkal az argumentumokkal hívja, amelyeket a metódus mezői leírnak. A Xuda úgy
válaszol, hogy belsőleg hívja a metódust, ugyanúgy, ahogy a /cpi/<method> tenné, és az eszköznek szövegként
adja vissza a metódus {code, data} burkolóját. A sikertelen hívás az MCP rétegben is normálisan tér vissza, a
-1 és afeletti kód pontosan úgy jelenik meg az eszköz eredményében, ahogy egy sima REST-hívásnál, így az
ügynök ugyanúgy olvassa, mint az Ön saját hibakezelése. Lásd a Hibák oldalt.
Az a kérés, amely bármilyen eszköz futása előtt meghiúsul, vagyis hiányzó vagy elutasított hitelesítő adat
(401), bezárt munkamenet (404, -32001 kód), hibás MCP-üzenet, eszközeredmény helyett JSON-RPC
hibaként jön vissza: