MCP
אותו מפתח API, חשוף לסוכן AI ככלי אחד עם טיפוסים לכל שיטה מותרת.
Xuda מריצה שרת Model Context Protocol בכתובת /mcp, לצד /cpi. מחברים אליו סוכן שתומך ב-MCP,
בהתחברות או עם מפתח API, וכל שיטה שהמפתח הזה רשאי לקרוא לה מופיעה ככלי עם טיפוסים, בלי שילוב
נפרד לסוכני AI לכתוב.
חיבור
יש שתי דרכים להיכנס, ושתיהן מסתיימות באותו מקום: הרשאות של מפתח API.
התחברות (מחברים של Claude ולקוחות OAuth אחרים)
מוסיפים את https://xuda.ai/mcp כמחבר מותאם אישית ב-Claude (Settings, Connectors, Add
custom connector), משאירים ריקים את מזהה הלקוח והסוד של OAuth, ולוחצים על Connect. Claude
פותחת את Xuda: מתחברים אם עוד לא התחברתם, וחלון בלוח הבקרה שואל באיזה מהמפתחות שלכם החיבור פועל.
בוחרים מפתח ולוחצים על חיבור. Claude באינטרנט, ב-Desktop, בנייד וב-Cowork חולקות את החיבור הזה,
וכל חשבון Claude אחר מוסיף אותו באותה דרך. הלשונית MCP תחת מפתחים בלוח הבקרה מציגה את
הכתובת להדבקה, את השלבים האלה ואת כל מה שבהמשך.
Claude Code מתחבר באותה דרך כשמוסיפים את השרת בלי כותרת, ואז מריצים /mcp ובוחרים
Authenticate:
לחיבור אף פעם אין הרשאות משלו. כל קריאה לכלי רצה כמפתח שבחרתם, ולכן מצב הגישה של המפתח, רשימת ההיתרים שלו והביטול שלו הם גם של החיבור: מבטלים את המפתח תחת מפתחים, מפתחות API והחיבור נעצר, וההתחברות הבאה מבקשת מפתח אחר. הדף מציג רק את המפתחות הפעילים שלכם; אם אין, יוצרים קודם אחד.
למפתחי לקוחות: השרת עוקב אחרי מפרט ההרשאה של MCP:
קריאה ל-/mcp בלי אסימון שמיש עונה 401 עם WWW-Authenticate: Bearer resource_metadata="...", וכך לקוח מוצא את השאר. אסימוני גישה תקפים לשעה; אסימוני רענון תקפים ל-90
יום ומוחלפים בכל שימוש. כתובת הפניה חוזרת של loopback (http://localhost או
http://127.0.0.1) מתאימה בכל פורט.
מפתח API בכותרת
המפתח עובר בכותרת Authorization: Bearer, אותו מפתח שהייתם משתמשים בו כ-api_key ב-/cpi. אין
אישור גישה נפרד ל-MCP. בקשה בלי כותרת Authorization, או עם מפתח שלא מתאים למסמך פעיל ב-
xuda_api_keys, נדחית ב-401 לפני שנרשם כלי כלשהו.
מושבים
התעבורה היא streamable HTTP: הבקשה הראשונה היא קריאת initialize של MCP, שפותחת מושב ומחזירה כותרת
mcp-session-id; כל בקשה הבאה באותו חיבור נושאת את אותה כותרת ואת אותו אישור גישה. מושב נסגר אחרי
10 דקות בלי בקשה. בקשה במושב שנסגר עונה 404, ולקוח MCP פותח אז מושב חדש מעצמו.
מה הופך לכלי
הכלים נרשמים בתחילת המושב לפי מצב הגישה שכבר יש למפתח:
- גישה מלאה: כל שיטה בקטלוג שאינה
privateנרשמת ככלי, נקבעת בזמן החיבור, ולכן שיטה שנוספה אחרי שהמפתח נוצר זמינה בלי שום שינוי במפתח עצמו. - גישה מותאמת: רק השיטות שברשימת ההיתרים של המפתח נרשמות.
מושב פעיל עוקב אחרי המפתח שלו: הוא בודק את המפתח כל דקה, ואת המודולים והפלאגינים שמאחוריו כל
חמש דקות, וכשקבוצת הכלים השתנתה הוא שולח notifications/tools/list_changed. לקוח שמאזין (Claude
מאזינה) קורא את הרשימה החדשה בלי להתחבר מחדש, ולכן שיטה שמתירים במפתח מגיעה לסוכן שכבר מחובר.
כל כלי שומר על הצורה של השיטה: שם הכלי הוא שם השיטה (get_account_projects,
dbs_read, ...), הכותרת שלו היא שם השיטה ב-Title Case, התיאור שלו הוא ה-description של השיטה
עצמה, וסכמת הקלט שלו נבנית שדה אחרי שדה מה-fields של השיטה: שדות חובה נשארים נדרשים, וכל השאר
אופציונלי. שדה בלי סוג מזוהה הופך בכל זאת לארגומנט מתירני של הכלי ולא שובר את המושב כולו, כך
ששיטה אחת עם הגדרה מוזרה לא מפילה איתה את שאר הקטלוג.
מפתח שמוגבל ל-Full Stack VPS חושף גם את כלי הפלאגינים המותקנים בתיבה הזאת, לצד שיטות המערכת שלמעלה, כך שסוכן יכול להגיע גם לפלטפורמה וגם לכל מה שהמפתח בנה בתיבה, במושב אחד. ראו Full Stack VPS.
קריאה לכלי
סוכן קורא לכלי עם אותם ארגומנטים שהשדות של השיטה מתארים. Xuda עונה בקריאה פנימית לשיטה, באותה
דרך ש-/cpi/<method> היה עושה, ומחזירה לכלי את מעטפת {code, data} של השיטה כטקסט. קריאה שנכשלה
עדיין חוזרת כרגיל בשכבת ה-MCP, קוד -1 ומעלה מופיע בתוצאת הכלי בדיוק כמו בקריאת REST רגילה, ולכן
סוכן קורא אותו כמו שהטיפול בשגיאות שלכם היה קורא. ראו שגיאות.
בקשה שנכשלת לפני שכלי כלשהו רץ, אישור גישה חסר או נדחה (401), מושב שנסגר (404, קוד -32001),
הודעת MCP פגומה, חוזרת כשגיאת JSON-RPC ולא כתוצאת כלי: