לדלג לתוכן

שרת MCP

ב-BombVault מובנה שרת עבור Model Context Protocol (MCP), הפרוטוקול שבו עוזרי בינה מלאכותית כמו Claude Code ו-Claude Desktop מגיעים לכלים חיצוניים. דרכו עוזר יכול לקרוא את מצב הגיבויים ואם הדבר מותר, להתחיל גיבוי או לבטל גיבוי שהוא עצמו התחיל. השרת כבוי עד שנוצר מפתח או שמופעלת התחברות דרך OAuth: עד אז נקודת הקצה /mcp עונה 404 על הכול.

מה עוזר יכול ומה לא

כלי מה הוא עושה סוג
get_health גרסה, שם המופע, האם רץ גיבוי ומה מותר למפתח הזה קריאה
get_status מצב ההגנה לפי תחום: הגיבוי המוצלח האחרון, המרווח הצפוי, אימותים ובדיקות off-site, ההרצות המתוזמנות הבאות, גיבויים שממתינים לאפליקציה שקטה, ולקונטיינרים גם בדיקת ההפעלה האחרונה קריאה
get_coverage מה BombVault מגן עליו ומה לא, עם הסיבה לכל אחד קריאה
list_items כל קונטיינר, VM וסט תיקיות מוגן, כונן ה-flash והגדרות האפליקציה, עם התזמון, מה שגיבוי עוצר, הגיבוי האחרון ומשכו. קונטיינרים של מסדי נתונים מציגים גם את ה-dump האחרון. גם datasets של ZFS מופיעים, עם תוצאת הבדיקה האחרונה שלהם. לכל פריט מצורפת בדיקת השחזור האחרונה שלו, ולקונטיינר גם בדיקת ההפעלה האחרונה או הסיבה שאי אפשר לבדוק אותו. קונטיינר שנוצר מחדש עם הגדרות אחרות מאז הגיבוי האחרון מפרט מה השתנה קריאה
list_runs היסטוריית הרצות, החדשות קודם, עם סינון לפי תחום, פריט, מצב, סוג וזמן. גיבוי איטי שדבר אחד בלם אותו מציין אותו קריאה
list_restore_points נקודות השחזור של פריט אחד מהמאגר הראשי שלו, ולקונטיינר גם ה-dumps של מסדי הנתונים שלו. ל-dataset של ZFS יש נקודת שחזור אחת לכל גיבוי, עם snapshot של כל dataset שמתחתיו קריאה
get_activity מה רץ עכשיו, עם שלב ואחוז קריאה
get_storage_stats היסטוריית הגודל של המאגר הראשי של תחום והגדילה השבועית שלו, וגם השטח התפוס, הפנוי והכולל בדיסק או ביעד המרוחק של כל אחד מהמאגרים שלו קריאה
get_size_breakdown אילו תיקיות וקבצים תופסים מקום בגיבוי החדש ביותר של קונטיינר, VM או סט תיקיות, וכמה מהם הוסיף הגיבוי האחרון קריאה
search_files מחפש קבצים ותיקיות לפי שם בגיבויים של כל הפריטים, של תחום אחד או של פריט אחד (לא מחפש במכונות וירטואליות), ומציג לכל תוצאה כל גיבוי שמכיל אותה קריאה
list_anomalies חריגות ש-BombVault הבחין בהן בגיבויים, עם סינון לפי מצב, חומרה ותחום וסיכום של מה שעדיין פתוח קריאה
get_anomaly אחת מהחריגות האלה, עם ההערה שנכתבה כשאושרה קריאה
start_backup מגבה פריט אחד מיד התחלה
start_domain_backup מגבה כל פריט מוגן בתחום אחד התחלה
start_backup_everything מריץ את סבב הגיבוי המלא התחלה
cancel_backup מבטל גיבוי רץ שהמפתח הזה התחיל ביטול

אלה נשארים בממשק האינטרנט: שחזור מכל סוג (כולל הורדה, שמירה או ייבוא של dump של מסד נתונים), מחיקת גיבויים, prune, unlock, בדיקות ותרגולים, שכפול off-site, הגדרות, פרטי התחברות ומפתחות MCP, וגם ביטול גיבוי שהתחילו התזמון, ממשק האינטרנט או מפתח אחר. כך גם אישור של חריגה או סימון שלה כצפויה, שנעשים בדף חריגות. הסיבה: התשובות של הכלים מכילות שמות והודעות שגיאה מהשרת, וכל אחד מהם עלול להכיל טקסט שנכתב כדי לכוון את העוזר. עוזר שנופל בפח כזה יכול לכל היותר להתחיל גיבוי בתוך המגבלות שלהלן, או לבטל גיבוי שהוא עצמו התחיל.

אם המאגר הראשי של פריט נמצא במקום אחר (S3,‏ REST,‏ SFTP,‏ rclone), ‏list_restore_points פונה אליו, והקריאה עשויה להימשך זמן מה. אי אפשר להציג עותקי off-site דרך MCP. ‏search_files קורא מאגרים מרוחקים, כולל עותקי off-site, רק כשהעוזר מבקש זאת, כי זה לוקח יותר זמן וחלק מהספקים גובים תשלום על הנתונים שהוא מוריד. חיפוש יכול להימשך דקות, ולכן הקריאה הראשונה מתחילה אותו ברקע וקריאה מאוחרת יותר אוספת את התוצאה. במה בדיקות החריגות מתבוננות מוסבר בחריגות, ואיך פריט ZFS שומר תמונת מצב אחת לכל מערך נתונים מוסבר במערכי נתונים של ZFS.

מה עושה גיבוי שהתחיל

גיבוי של עוזר הוא אותו גיבוי שממשק האינטרנט מתחיל. קונטיינר פועל נעצר עד שהגיבוי שלו מסתיים, יחד עם הקונטיינרים שהוגדרו להיעצר איתו. VM בשיטת "graceful" נכבה ומופעל מחדש. כל dataset של ZFS עוצר את הקונטיינרים שהוגדרו לו בזמן שה-snapshot שלו נלקח. סטים של תיקיות, כונן ה-flash וההגדרות ממשיכים לפעול. אחר כך BombVault מחיל את מדיניות השמירה ועשוי להעתיק למאגר ה-off-site. ‏list_items מספר לעוזר מה פריט עוצר וכמה זמן נמשך הגיבוי האחרון שלו, ותיאורי הכלים מבקשים ממנו לספר את זה למשתמש לפני שהוא מתחיל משהו.

מכיוון שגיבוי עוצר דברים ודוחק החוצה נקודות שחזור ישנות, התחלות דרך MCP מוגבלות:

  • 12 גיבויים שהתחילו לשעה לכל מפתח.
  • 15 דקות בין שתי התחלות MCP של אותו פריט, אותו תחום או הגיבוי המלא.
  • לכל היותר 4 התחלות MCP של אותו פריט ב-24 שעות.
  • שומר השמירה. כשתחום שומר מספר קבוע של נקודות שחזור (רק "שמור את N האחרונות", בלי כלל יומי, שבועי או חודשי, מקומית או ביעד off-site), כל גיבוי חדש דוחק החוצה את הישן ביותר. אז BombVault מסרב להתחלת MCP של פריט ש-N-1 הגיבויים המוצלחים החדשים ביותר שלו התחילו כולם דרך MCP. כך תמיד נשארת בסט השמור לפחות נקודת שחזור אחת שהתזמון או המשתמש יצרו. עם "שמור את האחרונה 1" עוזר לא יכול לגבות את הפריט הזה בכלל. הגיבוי המתוזמן הבא מפנה מקום מחדש. כלל שנתי לבדו נחשב כמו "שמור את האחרונה 1", כי הוא שומר נקודת שחזור אחת בלבד לשנה הנוכחית.

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

התחלות דרך ה-API ומ-Home Assistant נספרות באותן מגבלות לכל פריט יחד עם התחלות דרך MCP, וגם במגן השמירה.

הפעלה

  1. יש לפתוח את הגדרות, אינטגרציות, שרת MCP, ללחוץ על בחירת לקוח ולבחור את הלקוח בחלון. החיפוש בפינתו הימנית העליונה מוצא אותו לפי שם. לקוח שלא מופיע ברשימה מתחבר דרך לקוח אחר.
  2. תחת מפתח יש להשאיר את מפתח חדש ואת השם המוצע, שהוא שם הלקוח, או להקליד שם שאומר איפה המפתח משמש, למשל "Claude Code במחשב הנייד". מפתח אחד לכל לקוח מאפשר לבטל אחד בלי לגעת באחרים. מפתח קיים נותן ללקוח מפתח שנוצר קודם.
  3. יש להפעיל את אפשרות להתחיל גיבויים למפתח שצריך להיות מסוגל להתחיל גיבויים. בלי זה המפתח יכול רק לקרוא. אפשר לשנות את זה מאוחר יותר בפרטים של המפתח, והשינוי חל מהבקשה הבאה של העוזר, בלי חיבור מחדש.
  4. יש ללחוץ על יצירת מפתח. המפתח מוצג פעם אחת. BombVault שומר רק טביעת אצבע שלו ולא יוכל להציג אותו שוב, אז יש להעתיק אותו עכשיו. אם תסגור את החלון לפני שהלקוח השתמש במפתח, הכרטיס ימשיך להציג אותו עד לאישור שהוא הועתק.

בלי סיסמת כניסה ממשק האינטרנט עצמו פתוח לכל מי שברשת, ומי שיכול לפתוח אותו יכול גם ליצור מפתח. הכרטיס אומר זאת. אם פותחים את BombVault בשם שנראה ציבורי (למשל bombvault.example.com מאחורי reverse proxy) ולא הוגדרה סיסמת כניסה, אי אפשר ליצור או להחליף מפתחות מהכתובת הזו, כדי שאף דף באינטרנט לא יוכל לגרום לדפדפן ליצור מפתח. יש להגדיר סיסמת כניסה, או לפתוח את BombVault דרך כתובת ה-IP שלו או שם מקומי כמו tower או tower.local.

המפתחות והיומן שלהם

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

ליד השם, השורה מציגה את הסמל של הלקוח שעבורו נוצר המפתח. מפתח שנוצר דרך לקוח אחר, או לפני שהכרטיס הציג לקוחות, מציג במקום זה מפתח.

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

BombVault שומר את הרשומות של כל מפתח עד 30 יום: 500 ההפעלות והביטולים המוצלחים האחרונים, ולצידם 200 הקריאות האחרות האחרונות (קריאות נתונים, דחיות ושגיאות), כך שעוזר ששואל שוב ושוב על גיבוי שרץ או מנסה שוב ושוב קריאה שנדחתה לא יכול לדחוק את הפעלת הגיבוי מהיומן. לכל קריאה הוא שומר את הכלי, התוצאה וההרצה שביטול ציין. הוא אף פעם לא שומר את מה שהעוזר שלח, וגם לא את המפתח או טביעת האצבע שלו. חבילת האבחון רק סופרת את הרשומות, וייצוא ההגדרות משמיט אותן.

חיבור לקוח

בחירת לקוח פותח חלון עם כל לקוח כאריח, תחת במחשב הזה או בענן, וחיפוש בפינה הימנית העליונה. אריח פותח את ההגדרה של הלקוח באותו חלון, בשלושה שלבים: המפתח. התצורה ללקוח הזה, עם הכתובת שבה נפתח הכרטיס, כפתור העתקה, המקום שבו התצורה נמצאת, ועם האישור של BombVault עצמו גם מה שהלקוח צריך כדי לסמוך עליו. וההמתנה לקריאה הראשונה של הלקוח. החלון עוקב אחרי השימוש האחרון במפתח והופך לירוק כשהקריאה הזו מגיעה.

החלון מרחיק את המפתח מכל שורת פקודה. כשהלקוח יודע לקרוא אותו ממשתנה סביבה (BOMBVAULT_MCP_KEY), מבקשה מוסתרת או מקובץ משלו, התצורה רק מציינת אותו. כשאין ללקוח דרך כזו, המפתח נמצא בקובץ התצורה או בהגדרות שלו, והחלון אומר זאת. כשהתיעוד של לקוח לא אומר איך הוא מתייחס לאישור שהוא לא מכיר, החלון כותב את השלב הזה כמה לעשות אם הלקוח דוחה את האישור של BombVault.

לקוח הגדרה מאיפה המפתח מגיע
AnythingLLM קובץ תצורה קובץ התצורה
Antigravity קובץ תצורה משתנה סביבה
Claude Code פקודה קובץ מפתח
Claude Desktop קובץ תצורה קובץ מפתח
Cline קובץ תצורה קובץ התצורה
Codex CLI קובץ תצורה משתנה סביבה
Continue קובץ תצורה ~/.continue/.env
Copilot CLI קובץ תצורה קובץ התצורה
Cursor קובץ תצורה משתנה סביבה
Gemini CLI קובץ תצורה משתנה סביבה
GitHub Copilot (VS Code) קובץ תצורה בקשה מוסתרת
Goose קובץ תצורה משתנה סביבה
Jan טופס באפליקציה ההגדרות של האפליקציה
JetBrains (AI Assistant, Junie) קובץ תצורה קובץ התצורה
Kimi Code קובץ תצורה קובץ התצורה
LM Studio קובץ תצורה קובץ התצורה
Mistral Vibe קובץ תצורה משתנה סביבה
Msty טופס באפליקציה ההגדרות של האפליקציה
n8n טופס באפליקציה פרטי ההתחברות של n8n
Open WebUI טופס באפליקציה ההגדרות של האפליקציה
opencode קובץ תצורה משתנה סביבה
Perplexity (Mac) טופס באפליקציה קובץ מפתח
Qwen Code קובץ תצורה משתנה סביבה
Roo Code קובץ תצורה משתנה סביבה
Visual Studio קובץ תצורה קובץ התצורה
Warp קובץ תצורה קובץ התצורה
Windsurf קובץ תצורה משתנה סביבה
Zed קובץ תצורה קובץ התצורה
Grok טופס, בענן השרתים של הספק
Le Chat טופס, בענן השרתים של הספק
ChatGPT התחברות דרך OAuth, בענן אסימון גישה, פרטים למטה
Claude (claude.ai) התחברות דרך OAuth, בענן אסימון גישה, פרטים למטה

הסעיפים הבאים מסבירים בפירוט רב יותר את ההגדרה של Claude Code ו-Claude Desktop ומפרטים מה צריך כל לקוח אחר.

Claude Code

‏Claude Code מגיע ל-BombVault דרך mcp-remote, שצריך Node.js במחשב הזה. קודם יש לשמור את המפתח בקובץ טקסט נפרד, בשורה אחת:

X-API-Key: <your key>

אחר כך יש להריץ את הפקודה מהכרטיס פעם אחת במסוף, אחרי שמכניסים בה את הנתיב של הקובץ הזה. מאחורי תעודה שהמחשב סומך עליה היא נראית כך:

claude mcp add bombvault --scope user -- npx -y mcp-remote@latest https://bombvault.example.com/mcp --header-file "<path of the file with your key>"

עם התעודה של BombVault עצמו (פרטים בTLS ותעודות) הפקודה גם מפנה את Node.js לתעודה שהורדה:

claude mcp add bombvault --scope user -e "NODE_EXTRA_CA_CERTS=<path of the downloaded bombvault-cert.pem>" -- npx -y mcp-remote@latest https://192.168.1.10:3443/mcp --header-file "<path of the file with your key>"

יש לבדוק את החיבור עם /mcp בתוך Claude Code. ‏--scope user הופך את BombVault לזמין בכל הפרויקטים. ‏Claude Code שומר רק את הנתיב של קובץ המפתח, כך שהמפתח לא מופיע בפקודה ובהיסטוריה של המעטפת, ולא ברשימת התהליכים. יש לשמור את הקובץ במקום שאחרים לא יכולים לקרוא אותו, ומחוץ לכל תיקייה שמבצעים לה commit. ‏@latest גורם ל-npx להביא mcp-remote עדכני. בלעדיו תשמש במקומו גרסה ישנה יותר שמותקנת גלובלית, והיא לא מכירה את --header-file.

אין לכתוב את ${BOMBVAULT_MCP_KEY} בארגומנטים של mcp-remote עבור Claude Code. ‏Claude Code מציב הפניה כזו מהסביבה שלו לפני שהוא מפעיל את mcp-remote, כך שהמפתח מגיע לשורת הפקודה של התהליך הזה, ושם תוכנות אחרות ומשתמשים אחרים במחשב יכולים לקרוא אותו.

בלי Node.js, ורק מאחורי תעודה שהמחשב סומך עליה, Claude Code יכול להתחבר בעצמו. יש לשים קובץ .mcp.json בתיקיית הפרויקט:

{
  "mcpServers": {
    "bombvault": {
      "type": "http",
      "url": "https://bombvault.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${BOMBVAULT_MCP_KEY}"
      }
    }
  }
}

יש להגדיר את BOMBVAULT_MCP_KEY במקום שבו Claude Code מופעל, למשל תחת "env" ב-~/.claude/settings.json או בפרופיל המעטפת, דרך עורך טקסט ולא בהקלדה בשורת הפקודה. כאן ההפניה בטוחה, כי Claude Code לא מפעיל תהליך שני שהמפתח היה מגיע אליו. עם התעודה של BombVault עצמו זה לא עובד: החיבור ש-Claude Code יוצר בעצמו דוחה אותה גם כש-NODE_EXTRA_CA_CERTS מוגדר. לעולם אין לבצע commit לקובץ .mcp.json שהמפתח כתוב בו.

Claude Desktop

‏Claude Desktop מגיע ל-BombVault דרך mcp-remote, שצריך Node.js במחשב הזה. קודם יש לשמור את המפתח בקובץ טקסט משלו, בשורה אחת, כמו שמתואר עבור Claude Code. יש לפתוח את קובץ ההגדרות ב-Claude Desktop דרך Settings, Developer, Edit Config. הוא נמצא ב-%APPDATA%\Claude\claude_desktop_config.json ב-Windows וב-~/Library/Application Support/Claude/claude_desktop_config.json ב-macOS. יש להוסיף את הרשומה מהכרטיס בתוך "mcpServers", ליד השרתים שכבר נמצאים שם, ולהפעיל מחדש את Claude Desktop:

{
  "mcpServers": {
    "bombvault": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://192.168.1.10:3443/mcp", "--header-file", "<path of the file with your key>"],
      "env": {
        "NODE_EXTRA_CA_CERTS": "<path of the downloaded bombvault-cert.pem>"
      }
    }
  }
}
  • ‏NODE_EXTRA_CA_CERTS נמצא שם רק בשביל התעודה של BombVault עצמו. מאחורי תעודה שהמחשב כבר סומך עליה, יש להסיר אותו.
  • ‏--allow-http נוסף רק לכתובת http:// רגילה.
  • ב-Windows יש לכתוב את הנתיבים עם לוכסנים רגילים, למשל C:/Users/sam/bombvault-key.txt, כי לוכסן הפוך בודד אינו JSON תקין. יש לשמור את הנתיב של קובץ המפתח בלי רווחים: ‏Claude Desktop ב-Windows מעביר ל-npx נתיב עם רווח בשני חלקים.
  • התצורה מציינת רק את קובץ המפתח, כך שהמפתח לא מופיע בה וגם לא ברשימת התהליכים. יש לשמור את הקובץ במקום שאחרים לא יכולים לקרוא אותו.

לקוחות בענן

ChatGPT, Claude באתר claude.ai, Grok ו-Le Chat פונים ל-BombVault מהשרתים של הספק שלהם, ולכן BombVault חייב להיות נגיש מהאינטרנט עם אישור מהימן ציבורית, למשל מאחורי פרוקסי הפוך. Le Chat דוחה אישורים בחתימה עצמית. התחברות בפרוקסי יכולה להגן על ממשק האינטרנט, אבל /mcp חייב להגיע ל-BombVault בלעדיה: השירותים האלה לא יודעים להתחבר לפרוקסי, ו-BombVault בודק את המפתח או האסימון שלהם בעצמו. Grok ו-Le Chat שולחים מפתח קבוע, והכפתורים שלהם מגדירים אותם כמו את האחרים. ChatGPT, וברוב הארגונים גם Claude באתר claude.ai, מתחברים רק דרך התחברות עם OAuth, שמתוארת בהמשך.

התחברות דרך OAuth

ללקוח שלא יכול לקבל מפתח, BombVault הוא שרת ההרשאות של OAuth עבורו. הלקוח רושם את עצמו, שולח את המשתמש לדף של BombVault, ושם מתחברים עם סיסמת הכניסה (ועם הגורם השני, אם הוגדר) ומאשרים אותו. אחר כך הלקוח מקבל אסימון שתקף רק לנקודת הקצה של MCP ב-BombVault הזה, ומחדש אותו בעצמו.

  1. יש להגדיר סיסמת כניסה תחת הגדרות, אבטחה. בלי סיסמה BombVault לא מציע התחברות בכלל, כי לא יהיה את מי לשאול להסכמה.
  2. הפוך את BombVault לנגיש מהאינטרנט ב-https עם אישור שדפדפנים סומכים עליו, בדרך כלל דרך פרוקסי הפוך. הלקוח פונה אל /mcp, /oauth/ ו-/.well-known/ מהשרתים שלו, ולכן פרוקסי עם התחברות משלו חייב להעביר את שלושת הנתיבים האלה אל BombVault. דף ההסכמה ב-/oauth/authorize נפתח בדפדפן ויכול להישאר מאחורי ההתחברות של הפרוקסי. ציין גם את ה-proxy ב-TRUSTED_PROXY (פרטים בהגדרות). BombVault מגביל רישומי לקוחות לפי כתובת, ובלי זה כל לקוח נראה כאילו הוא מגיע מה-proxy.
  3. בכרטיס MCP יש להפעיל את התחברות דרך OAuth ולהזין את כתובת ציבורית: כתובת ה-https בלי נתיב, למשל https://backup.example.com. כל אסימון קשור לכתובת הזו, לכן אחרי שינוי כל לקוח צריך להתחבר מחדש.
  4. יש לבחור ב-ChatGPT או ב-Claude תחת בחירת לקוח. החלון מציג את כתובת המחבר, כלומר הכתובת הציבורית עם /mcp בסופה, ואיפה היא נכנסת בלקוח הזה. ב-ChatGPT מפעילים את מצב המפתחים תחת הגדרות, אפליקציות ומחברים, הגדרות מתקדמות, בוחרים צור, מדביקים את כתובת המחבר ככתובת שרת ה-MCP ובוחרים OAuth כאימות. ב-claude.ai פותחים הגדרות, מחברים, הוסף מחבר מותאם אישית, מדביקים את כתובת המחבר, משאירים ריקים את מזהה הלקוח והסוד של OAuth ובוחרים התחבר.
  5. הלקוח פותח את דף ההסכמה. הדף מראה מי מבקש, לאן התשובה תחזיר את המשתמש, ואת המתג אפשרות להתחיל גיבויים, שמתחיל כבוי. יש לבחור אישור או דחייה.

כל לקוח שהתחבר מקבל שורה משלו באותה רשימה, עם הסמל שלו. בפרטים שלו נמצאים היומן, ביטול ו-אפשרות להתחיל גיבויים, ויש לו אותן מגבלות כמו מפתח. ביטול נכנס לתוקף מיד. כשאותו לקוח מתחבר שוב, ההרשאה החדשה שלו מחליפה את הישנה, והרשאה שאיש לא השתמש בה 30 ימים פגה. עד 10 לקוחות יכולים להיות מחוברים בו-זמנית, בנוסף ל-10 המפתחות.

דף ההסכמה מקבל בקשה רק מלקוח רשום שמציין בדיוק אחת מכתובות החזרה הרשומות שלו: https, או כתובת loopback בכל פורט עבור לקוח במחשב המקומי. מתקבלת רק זרימת קוד ההרשאה עם PKCE (S256), והתשובה קשורה לסשן, כך שאף אתר אחר לא יכול לשלוח אותה בשם המשתמש. אסימוני גישה תקפים לשעה. אסימון רענון מוחלף בכל שימוש, ואם אחד מהם מופיע שוב אחר כך, BombVault מבטל את ההרשאה, כי למישהו אחר יש עותק. לקוח שחוזר על הרענון האחרון שלו בתוך 30 שניות, כי התשובה לא הגיעה אליו, מקבל במקום זאת אסימונים חדשים. BombVault לא מוריד מטא-נתונים של לקוחות מהאינטרנט, ולכן לקוחות נרשמים דרך רישום לקוחות דינמי.

לקוחות אחרים

כל לקוח שמדבר Streamable HTTP מתאים:

  • כתובת URL: כתובת ממשק האינטרנט ועוד /mcp, למשל https://192.168.1.10:3443/mcp.
  • המפתח ב-Authorization: Bearer <key> או ב-X-API-Key: <key>. אם נשלחים שניהם, הם חייבים לשאת את אותו מפתח.
  • ‏POST עם Content-Type: application/json ו-Accept: application/json, text/event-stream.
  • הודעת JSON-RPC אחת לכל בקשה. אצוות (batch) נדחות.
  • גרסאות הפרוטוקול 2026-07-28, ‏2025-11-25, ‏2025-06-18 ו-2025-03-26.

TLS ותעודות

‏BombVault מגיש HTTPS עם תעודה שהנפיק בעצמו, ובהתחלה התעודה הזו מזכירה רק את localhost, ‏127.0.0.1 ו-::1. ‏Claude Code ו-mcp-remote דוחים אותה בכתובת ברשת המקומית. הדרכים לעקוף זאת, בסדר שמתאים לרוב התקנות Unraid:

  1. הוספת הכתובת בכרטיס MCP. כשפותחים את הכרטיס ב-HTTPS בכתובת שהתעודה לא מזכירה, הכרטיס אומר זאת ומציע הוספת הכתובת הזאת לאישור. ‏BombVault מנפיק אז את התעודה מחדש עם הכתובת הזו (הדפדפן מזהיר עוד פעם אחת, כמו בפעם הראשונה). אחר כך יש ללחוץ על הורדת אישור. הקטעים מגדירים את NODE_EXTRA_CA_CERTS לקובץ שהורד, כך שהלקוח סומך בדיוק על התעודה הזו. המשמעות היא גם שכל לקוח שהוגדר עם קובץ שהורד קודם מפסיק להתחבר ברגע שהתעודה מונפקת מחדש, במחשב הזה ובכל מחשב אחר, עד שהוא מקבל את הקובץ החדש.
  2. ‏Reverse proxy עם תעודה מהימנה (Nginx Proxy Manager,‏ SWAG,‏ Caddy,‏ Traefik). הלקוח רואה אז את התעודה של ה-proxy ולא צריך שום דבר נוסף, והכרטיס לא מזהיר לגבי התעודה של BombVault.
  3. ‏Tailscale. ‏tailscale serve לפני הקונטיינר, או שילוב Tailscale ב-Unraid, נותן שם ts.net עם תעודה מהימנה.
  4. ‏HTTP_ONLY=true, רק מאחורי proxy שמסיים את ה-TLS או ברשת מהימנה לגמרי. הוא מעביר את כל ממשק האינטרנט ל-HTTP רגיל, דורש שינוי בהגדרות הקונטיינר ושולח את המפתח בלי הצפנה.

לעולם אין להגדיר NODE_TLS_REJECT_UNAUTHORIZED=0. זה מכבה את בדיקת התעודות לכל מה שתהליך ה-Node.js הזה מדבר איתו.

‏Reverse proxy חייב להעביר את הכותרת Authorization (או X-API-Key), מה ש-proxy עושים אלא אם אומרים להם אחרת, ואסור לו לאגור את /mcp בחוצץ או לשכתב אותו. בלוק location ל-Nginx או ל-Nginx Proxy Manager שבודק גם את התעודה של BombVault:

location /mcp {
    proxy_pass https://192.168.1.10:3443;
    proxy_ssl_verify on;
    proxy_ssl_trusted_certificate /data/bombvault-cert.pem;
    proxy_ssl_name localhost;
    proxy_http_version 1.1;
    proxy_buffering off;
    proxy_set_header Host $host;
}

מאחורי proxy כל בקשה נושאת את הכתובת של ה-proxy. חמישה מפתחות שגויים מלקוח אחד שהוגדר לא נכון נועלים אז בחוץ לדקה את כל לקוחות ה-MCP שמאחורי אותו proxy. ציין את ה-proxy ב-TRUSTED_PROXY (פרטים בהגדרות) כדי שהספירה תהיה לכל לקוח.

מודל האבטחה

  • בלי מפתח פעיל וכשההתחברות דרך OAuth כבויה, /mcp עונה 404.
  • התחברות דרך OAuth מוצעת רק כל עוד מוגדרת סיסמת כניסה. אסימונים, קודים וסודות של לקוחות נשמרים רק כטביעת אצבע, ואסימון תקף רק לכתובת שעבורה הונפק.
  • לקוח יכול להירשם לכל היותר 10 פעמים בשעה מכתובת אחת, ו-BombVault שומר לכל היותר 100 לקוחות רשומים שאיש לא התחבר דרכם, כל אחד ליום אחד. קודים ואסימוני רענון שגויים נספרים לאותה נעילה כמו מפתחות שגויים.
  • הרשאות מתנהגות כמו מפתחות בשחזור גיבוי של ההגדרות או בשינוי APP_KEY: אחרי שחזור כל לקוח צריך להתחבר מחדש.
  • אין כתובות פטורות. בקשות מ-localhost, ממארח ה-Unraid, מ-reverse proxy או מ-tailscale serve צריכות מפתח כמו כל בקשה אחרת, גם כשלממשק האינטרנט אין סיסמת כניסה.
  • מפתחות נשמרים רק כטביעות אצבע, מוצגים פעם אחת, ואפשר לשנות את שמם, להחליף ולבטל אותם. עד 10 מפתחות פעילים, לכל אחד מתג משלו אפשרות להתחיל גיבויים.
  • כל יצירה, החלפה, שינוי הרשאה וביטול שולחים התראה דרך ערוצי ההתראות, עם הכתובת שממנה הגיעו, אלא אם ההתראות כבויות.
  • 5 מפתחות שגויים לדקה לכל כתובת, ואחר כך 429. ‏120 בקשות לדקה ו-12 גיבויים שהתחילו לשעה לכל מפתח, ובנוסף זמן ההמתנה ושומר השמירה שתוארו למעלה.
  • בקשות מדף דפדפן ממקור (origin) אחר נדחות.
  • כל עוד לא הוגדרה סיסמת כניסה, אי אפשר ליצור מפתחות משם מארח שנראה ציבורי.
  • כל גיבוי שעוזר מתחיל, והרצות ה-prune וה-off-site שנובעות ממנו, מסומנים "דרך MCP" עם שם המפתח ביומן הפעילות, בחלונית השגיאות ובהתראת הגיבוי.
  • כל קריאה לכלי נכתבת ביומן הקונטיינר עם מזהה המפתח וארבעת התווים האחרונים שלו (אף פעם לא עם השם) ונספרת ב-/metrics ‏(bombvault_mcp_requests_total, ‏bombvault_mcp_tool_calls_total, ‏bombvault_mcp_active_keys).
  • שחזור גיבוי של ההגדרות מבטל את כל המפתחות, כי מסד הנתונים המשוחזר עלול להכיל מפתחות שבוטלו אחרי שנשמר. יש ליצור מפתחות חדשים אחר כך.
  • מפתח מפסיק לעבוד כש-APP_KEY משתנה (התקנה מחדש או שחזור לקונטיינר אחר). הכרטיס מזהה זאת ומסמן את המפתח, והחלפת מפתח נותן לו שוב סוד תקף.
  • התייחס למפתח כמו לסיסמה. לקוח שלא יכול לקרוא את המפתח ממשתנה סביבה, מבקשה או מקובץ מפתח שומר אותו כטקסט רגיל בתצורה או בהגדרות שלו, וההגדרה שלו אומרת זאת. במחשב פחות מהימן, עדיף מפתח לקריאה בלבד.

מה יוצא מהמכונה

כל מה שעוזר קורא הולך לספק הבינה המלאכותית שמאחוריו: שמות פריטים, תזמונים, היסטוריית הרצות עם הודעות שגיאה, מזהים וזמנים של נקודות שחזור, שמות מנועי מסדי נתונים וגדלים של dumps, הפעילות הנוכחית, נתוני אחסון, כיסוי ומצב. חיפוש קבצים שולח גם את הקבצים שהוא מוצא: את השמות, הגדלים והנתיבים שלהם בתוך הגיבוי. ‏BombVault מסיר נתיבי מארח, מיקומי מאגרים, שמות מארחים, פרטי התחברות, פקודות hook ומפתחות לפני שמשהו יוצא.

פתרון בעיות

מה שמופיע מה זה אומר
404 אין מפתח פעיל וההתחברות דרך OAuth כבויה, או נתיב שגוי כמו /api/mcp. נקודת הקצה היא /mcp.
401 המפתח חסר, מוקלד לא נכון, בוטל או הוחלף. אולי proxy משמיט את הכותרת Authorization (יש לנסות X-API-Key). אם הכרטיס מסמן את המפתח כלא תקף יותר, APP_KEY השתנה: יש להחליף את המפתח.
403 הבקשה הגיעה מדף דפדפן ממקור אחר. יש להשתמש בלקוח שולחני או בלקוח שורת פקודה.
405 ב-GET תקין. נקודת החיבור מקבלת רק POST.
400 "Accept must contain both 'application/json' and 'text/event-stream'" הלקוח ישן מדי בשביל Streamable HTTP. יש לעדכן אותו.
400 "batch requests are not accepted" הלקוח שולח אצוות JSON-RPC. שלח הודעה אחת לכל בקשה.
429 יותר מדי מפתחות שגויים מהכתובת הזו, או יותר מ-120 בקשות לדקה עם מפתח אחד. יש לחכות דקה ולבדוק שהעוזר לא נתקע בלולאה.
שגיאות עם "certificate",‏ "self-signed" או "unable to verify" הלקוח לא סומך על התעודה של BombVault. פרטים בTLS ותעודות.
busy גיבוי אחר או משימת תחזוקה תופסים את התחום. יש לנסות שוב כשהיא מסתיימת.
cooldown הפריט הזה, התחום הזה או הגיבוי המלא הותחל מחוץ לממשק לפני פחות מ-15 דקות.
retention_guard עוד גיבוי MCP היה משאיר בחלון "שמור את N האחרונות" רק נקודות שחזור מ-MCP, או שהפריט כבר קיבל 4 גיבויים דרך MCP ב-24 השעות האחרונות, כולל גיבויים שנכשלו או בוטלו. במקרה הראשון הגיבוי המתוזמן הבא מפנה מקום, ובשני הפריט מתפנה שוב 24 שעות אחרי הישן מביניהם. מממשק האינטרנט אפשר להתחיל אותו בכל עת.
rate_limited המפתח ניצל את 12 ההתחלות שלו לשעה הזו.
not_permitted בהתחלה המפתח יכול רק לקרוא. יש להפעיל את אפשרות להתחיל גיבויים בכרטיס. אין צורך בחיבור מחדש. בביטול זה אומר שההרצה לא הותחלה על ידי המפתח הזה.
domain_off התחום הזה כבוי בהגדרות, כללי.
not_found ‏BombVault לא מגן על הפריט הזה. יש להוסיף אותו קודם בממשק האינטרנט. MCP אף פעם לא יוצר הגדרות.
הלקוח לא מוצא את שרת ההרשאות ההתחברות דרך OAuth כבויה, לא הוגדרה סיסמת כניסה, או שהפרוקסי לא מעביר את /.well-known/ אל BombVault.
דף ההסכמה אומר שכתובת החזרה לא רשומה הלקוח שלח כתובת חזרה שלא רשם. יש להסיר את המחבר בלקוח ולהוסיף אותו מחדש.
לקוח מחובר מקבל 401 ההרשאה שלו בוטלה, פגה אחרי 30 ימים ללא שימוש, או שהכתובת הציבורית השתנתה. הלקוח יתחבר מחדש.

אין להגדיר לקונטיינר את משתנה הסביבה MCPGODEBUG. הוא משנה את התנהגות ספריית ה-MCP, וערך שגוי עוצר את BombVault בהפעלה עוד לפני שהוא כותב שורת יומן אחת.