דילוג לתוכן
אומת

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:

claude mcp add
claude mcp add --transport http xuda https://xuda.ai/mcp

לחיבור אף פעם אין הרשאות משלו. כל קריאה לכלי רצה כמפתח שבחרתם, ולכן מצב הגישה של המפתח, רשימת ההיתרים שלו והביטול שלו הם גם של החיבור: מבטלים את המפתח תחת מפתחים, מפתחות API והחיבור נעצר, וההתחברות הבאה מבקשת מפתח אחר. הדף מציג רק את המפתחות הפעילים שלכם; אם אין, יוצרים קודם אחד.

למפתחי לקוחות: השרת עוקב אחרי מפרט ההרשאה של MCP:

קריאה ל-/mcp בלי אסימון שמיש עונה 401 עם WWW-Authenticate: Bearer resource_metadata="...", וכך לקוח מוצא את השאר. אסימוני גישה תקפים לשעה; אסימוני רענון תקפים ל-90 יום ומוחלפים בכל שימוש. כתובת הפניה חוזרת של loopback (http://localhost או http://127.0.0.1) מתאימה בכל פורט.

מפתח API בכותרת

claude mcp add
claude mcp add --transport http xuda https://xuda.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

המפתח עובר בכותרת 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 חושף גם את כלי הפלאגינים המותקנים בתיבה הזאת, לצד שיטות המערכת שלמעלה, כך שסוכן יכול להגיע גם לפלטפורמה וגם לכל מה שהמפתח בנה בתיבה, במושב אחד. ראו Full Stack VPS.

קריאה לכלי

סוכן קורא לכלי עם אותם ארגומנטים שהשדות של השיטה מתארים. Xuda עונה בקריאה פנימית לשיטה, באותה דרך ש-/cpi/<method> היה עושה, ומחזירה לכלי את מעטפת {code, data} של השיטה כטקסט. קריאה שנכשלה עדיין חוזרת כרגיל בשכבת ה-MCP, קוד -1 ומעלה מופיע בתוצאת הכלי בדיוק כמו בקריאת REST רגילה, ולכן סוכן קורא אותו כמו שהטיפול בשגיאות שלכם היה קורא. ראו שגיאות.

בקשה שנכשלת לפני שכלי כלשהו רץ, אישור גישה חסר או נדחה (401), מושב שנסגר (404, קוד -32001), הודעת MCP פגומה, חוזרת כשגיאת JSON-RPC ולא כתוצאת כלי:

json
{ "jsonrpc": "2.0", "error": { "code": -32000, "message": "Bad Request: Invalid Api key" }, "id": null }

הצעד הבא