התקנה בכל סוכן

התוסף כבר נושא בתוכו את הגדרת שרת ה‑MCP. כל מה שהוא צריך מכם הוא שני ערכים — Application Id ו‑API Key — ואחריהם, מסלול התקנה אחד מתוך שלושה, לפי סוג הסוכן שלכם.

שלב	מה עושים	כמה זמן
1	מפיקים Application Id ומפתח API	דקה
2	מתקינים את התוסף ומדביקים את שני הערכים	דקה
3	מוכיחים שהחיבור עובד	דקה

שלב 1 הוא השלב היחיד שדורש כניסה למערכת. אין לכם עדיין מערכת? פתיחת מערכת חדשה — 14 יום חינם.

הסוכן	המסלול	איפה המפתח נשמר
Claude Code	§2א — פקודות marketplace	בכספת של מערכת ההפעלה
Codex · Cursor · GitHub Copilot · VS Code · Kiro	§2ב — Agent Plugins 1.0	בקובץ mcp.json על הדיסק
ChatGPT Work · Claude Cowork · כל לקוח MCP אחר	§2ג — MCP connector ישיר	לפי מנגנון האחסון של אותו לקוח

שלב 1 — הוציאו את שני ערכי החיבור

שני הערכים נמצאים על אותו מסך, ואתם מייצרים אותם בעצמכם — בלי פנייה לתמיכה.

1. בתוך ה‑CRM, לחצו על החץ שליד שם המשתמש (פינה שמאלית עליונה) ← סביבת פיתוח / Development environment. נפתחת לשונית חדשה.
2. בסרגל הצד: Databases ← בסיס הנתונים שלכם (בדרך כלל DB for MyBusiness).
3. לשונית Settings — הכרטיס הראשון הוא Application Id, עם כפתור Copy.
4. מתחתיו טבלת API Keys: + Add Key ← שם ← Save ← רענון המסך ← העתקה.

שלוש עובדות על המסך הזה

1. Add Key יוצר מפתח חי מיד — הוא נשמר בשרת עוד לפני Save (אחרי רענון הוא מופיע עם Created Date). מפתח שנוצר בטעות מבטלים ב‑Revoke; סגירת הדף לא מוחקת אותו.
2. Save שומר את ה‑Name. שם שהוקלד ונשמר שורד רענון מלא — אפשר להסתמך עליו כדי להבחין בין מפתחות.
3. מגבלה ידועה — עד 5 מפתחות לבסיס נתונים. כשיש חמישה, הקישור + Add Key פשוט נעלם, בלי הודעה. בטלו מפתח ישן כדי לפנות מקום.

מה המפתח הזה נותן: גישה מלאה לבסיס הנתונים — כל טבלה, כל רשומה, כולל _User — בלי קשר לתפקידים והרשאות, והפעולות נרשמות בשם Master ולא בשם אדם. מתייחסים אליו כמו לסיסמה. היתרון היחיד שלו על Master Key הוא ביטול נקודתי: לחיצה על סמל הפח בעמודת Revoke מבטלת אותו מיידית, בלי לגעת בשום דבר אחר. פירוט מלא: אימות והרשאות.

שלב 2א — Claude Code

/plugin marketplace add AviMYB/mybusiness-plugins
/plugin install mybusiness-implementor@mybusiness
/plugin configure mybusiness-implementor@mybusiness
/reload-plugins

הפקודה השלישית פותחת טופס עם שני שדות — Application Id ו‑API key. השדות מוגדרים במניפסט של Claude Code כ‑userConfig:

השדה	type	חובה	sensitive
application_id	String	✔	—
api_key	String	✔	✔

הדגל sensitive הוא ההבדל שקובע: הערך נשלח לכספת של מערכת ההפעלה ולא נכתב לקובץ הגדרות. הקובץ .mcp.json שבתוך התוסף מפנה אליו בהצבעה, ולא מכיל את הערך עצמו:

JSON

{
  "mcpServers": {
    "MyBusiness": {
      "type": "http",
      "url": "https://mcp.mbapps.co.il/",
      "headers": {
        "X-Parse-Application-Id": "${user_config.application_id}",
        "X-Parse-API-Key": "${user_config.api_key}"
      }
    }
  }
}

/reload-plugins איננו קישוט

הגדרת MCP אינה נטענת חם. בלי הפקודה הרביעית (או הפעלה מחדש של הלקוח) השרת ממשיך לרוץ עם הערכים הישנים — ולרוב עם ערכים ריקים, מה שמופיע כ‑Authorization header is required.

התקנה בשורת פקודה אחת

אותם ערכים אפשר להעביר כבר בהתקנה:

Bash

claude plugin install mybusiness-implementor@mybusiness \
  --config application_id=YOUR_APPLICATION_ID \
  --config api_key=YOUR_API_KEY

אם אתם מעדיפים חיבור ברמת הפרויקט

אפשר לוותר על הקונפיגורציה של התוסף, לכבות את השרת שלו ב‑/mcp, ולרשום שרת משלכם:

Bash

claude mcp add --transport http MyBusiness https://mcp.mbapps.co.il/ \
  --header "X-Parse-Application-Id: YOUR_APPLICATION_ID" \
  --header "X-Parse-API-Key: YOUR_API_KEY"

--scope project כותב את המפתח לתוך הריפו

עם ה‑scope הזה הערכים נוחתים ב‑.mcp.json בתוך הפרויקט — כלומר בתוך גיט. אל תבצעו commit למפתח. אם כבר קרה: Revoke על אותה שורה במסך ה‑Settings, וייצור מפתח חדש. מחיקת השורה מהקובץ אינה מבטלת את המפתח.

שלב 2ב — סוכן שתומך בתקן Agent Plugins 1.0

מתקינים את תיקיית התוסף כפי שהסוכן שלכם מתקין תוספים — clone של המאגר, או העתקה של plugins/mybusiness-implementor/ למיקום שהלקוח קורא ממנו — ואז:

1. פותחים את mcp.json שבתוך תיקיית התוסף.
2. מחליפים את שני ה‑placeholders בערכים משלב 1.
3. מפעילים מחדש (או טוענים מחדש) את הלקוח.

JSON

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "MyBusiness": {
      "type": "streamable-http",
      "url": "https://mcp.mbapps.co.il/",
      "headers": {
        "X-Parse-Application-Id": "REPLACE_WITH_YOUR_APPLICATION_ID",
        "X-Parse-API-Key": "REPLACE_WITH_YOUR_API_KEY"
      }
    }
  }
}

בפורמט הפתוח אין כספת

לתקן Agent Plugins 1.0 אין מנגנון לסודות שהמשתמש מספק — כותרות ב‑mcp.json הן, בלשון המפרט עצמו, visible package data, not secure. ברגע שהדבקתם שם מפתח, הוא יושב בקובץ טקסט על הדיסק. לכן:

• אל תעלו את עותק התוסף הזה ל‑repository ואל תבצעו לו commit.
• בטלו את המפתח (Settings ← API Keys ← Revoke) כשהמכונה או האדם כבר לא צריכים אותו.
• אם ללקוח שלכם יש מנגנון אחסון סודות משלו או החלפת משתני סביבה — העדיפו אותו על עריכת הקובץ.

הבדל טכני נוסף בין שני הפורמטים: type הוא "streamable-http" בתקן הפתוח ו‑"http" בפורמט של Claude Code. אלה שני שמות לאותה תעבורה — אל תעתיקו את אחד לתוך השני.

שלב 2ג — סוכן שאינו מתקין תוספים

כל לקוח שמדבר MCP יכול להשתמש בחיבור גם בלי מנגנון תוספים. ב‑ChatGPT Work או Claude Cowork מוסיפים connector מותאם לכתובת:

https://mcp.mbapps.co.il/

עם שתי אותן כותרות — X-Parse-Application-Id ו‑X-Parse-API-Key. הסקילים שבתיקייה הם קובצי Markdown רגילים תחת skills/, וניתן לקרוא אותם כמסמכים גם היכן שאי אפשר לטעון אותם אוטומטית.

או — התחברות משתמש, בלי מפתח בכלל

לקוחות שרצים בדפדפן יכולים להתחבר במצב OAuth 2.1 במקום עם מפתח: מוסיפים connector לאותה כתובת בלי כותרות, והשרת מפנה למסך ההתחברות של ה‑CRM. החיבור אז פועל בזהות המשתמש שהתחבר — התפקיד שלו, בתוספת ההרשאות האישיות בלשונית MCP Permissions.

שלוש אזהרות על המצב הזה

1. למשתמשים אין גישת MCP כברירת מחדל. מנהל מעניק אותה פעם אחת לכל משתמש: הגדרות ← הכרטיס “משתמשים” ← עיפרון על כרטיס המשתמש ← לשונית MCP Permissions ← Apply. בלשונית ארבע תיבות: Read / Create / Update, ו‑Edit pages and schema (דורשת תפקיד Admin). בלי זה ההתחברות מצליחה וכל קריאת כלי נכשלת ב‑403 No permissions to access the MCP server.
2. מגבלה ידועה — ההרשאות כפופות לחבילת המנוי. במערכת ללא חבילה (סביבת ניסיון/סנדבוקס) התיבות מנוטרלות ו‑Apply אינו שולח דבר — אי אפשר להפעיל את מצב ההתחברות שם.
3. לקוחות שולחן עבודה ו‑CLI אינם יכולים להשלים את הזרימה הזו כרגע — כתובת callback מסוג http://localhost נדחית ב‑403 עוד לפני שהיא מגיעה לשרת. שם משתמשים ב‑Application Id + API Key. ראו מגבלת ה‑OAuth.

שלב 3 — הוכיחו שהחיבור עובד

סטטוס ירוק אינו הוכחה. השרת עונה ל‑initialize ומחזיר רשימת כלים מלאה (67 כלים) גם בלי אימות — רק tools/call נאכפת, ובלי כותרות היא מחזירה HTTP 403 עם Authorization header is required. לכן לקוח יכול להיראות מחובר, להציג את כל הכלים, ולהיכשל בקריאת הנתונים הראשונה.

שלוש קריאות, בסדר הזה:

#	הקריאה	תשובה תקינה	מה זה מוכיח
1	Usage-Guide	טקסט ההוראות של השרת	התעבורה עובדת ואתם מדברים עם שרת MyBusiness
2	Get-Current-User	המשתמש שהתחבר · או הזהות הסינתטית {"objectId":"Master","username":"Master",…} (בשרת ישן: Error: User name not found)	האימות עובד — ובאיזה מצב אתם
3	Get-Schema (בלי פרמטרים)	אובייקט שהמפתחות שלו הם שמות הטבלאות	הגעתם לבסיס נתונים אמיתי — הקריאו למשתמש 3–4 שמות טבלה לאישור

Get-Current-User הוא כל המבחן: אובייקט משתמש אמיתי ⇒ מצב התחברות, מודע‑הרשאות. username: "Master" ⇒ מצב Application Id + API Key, ברמת master — כלומר שום דבר לא מגן על הנתונים חוץ מכם. בגרסאות שרת עדכניות הכלי מחזיר במצב הזה רשומה סינתטית שה‑objectId שלה הוא המחרוזת Master — אל תשתמשו בה כ‑Pointer ל‑_User.

מגבלה ידועה — Get-Triggers נכשל בחיבור API Key

בחיבור Application Id + API Key, Get-Triggers מחזיר Error: Not Found (עם או בלי tableName), בעוד Set-Trigger, Set-Trigger-Action, Get-Data ו‑Get-Schema עובדים עם אותו מפתח. הסקילים שקוראים טריגרים לפני כתיבה — myb-p-trigger-setup, myb-p-timestamp-field, myb-p-sla-configuration, myb-p-data-import, myb-p-csat-survey — לא יוכלו לבצע את צעד הקריאה במצב הזה. עד לתיקון: קוראים את רשימת הטריגרים בסביבת הפיתוח (Databases ← DB ← Triggers), או מתחברים עם Master Key לצעד הזה בלבד.

רק אחרי שהמשתמש אישר שזה בסיס הנתונים הנכון — כותבים משהו.

שלב 4 — הקריאה הראשונה

פתחו שיחה חדשה ובקשו, למשל: “תקים לי מודול ניהול ספקים עם דף רשימה ודשבורד”. הסקילים נטענים ומופעלים אוטומטית לפי ניסוח הבקשה. ואם משהו לא ברור — כתבו “תחבר אותי למערכת שלי”, והסקיל myb-p-getting-started ילווה אתכם ויוכיח שהחיבור עובד.

פתרון תקלות התקנה

מה אתם רואים	מה זה אומר	התיקון
Authorization header is required (HTTP 403, JSON‑RPC -32000)	הקריאה הגיעה בלי אישורים בכלל — השדות ריקים, או שהתוסף לא נטען מחדש אחרי מילוי. קורה גם ל‑Usage-Guide	/plugin configure … ואז /reload-plugins
Permission denied for action find on class … על כל טבלה, ו‑Usage-Guide עדיין עובד	פרטי הגישה שגויים: שגיאת הקלדה, מפתח שבוטל, מפתח מבסיס נתונים אחר — או המפתח הנכון תחת שם כותרת שגוי	העתיקו מחדש; ודאו שהכותרת היא X-Parse-API-Key ולא X-Parse-Master-Key; /reload-plugins
Failed to get admin session with master key מ‑Get-Current-User, או Error: no user מ‑Get-Schema	אותה סיבה בדיוק — פרטי גישה שגויים, נוסח שונה מכלי לכלי	כנ“ל
Error: Not Found מ‑Get-Triggers בלבד	מגבלה ידועה של חיבור API Key — לא בעיית פרטי גישה	ראו התיבה בשלב 3
invalid_token	קיים token של התחברות אבל הוא נדחה — פג, בוטל, או הונפק למערכת אחרת	/mcp ← השרת ← אימות מחדש
לשונית ההתחברות מסתיימת ב‑403	ה‑callback המקומי של לקוח שולחן עבודה נדחה לפני שהגיע לשרת	עברו ל‑Application Id + API Key
אין כלי MyBusiness בכלל	השרתים של התוסף לא נטענו — הותקן באמצע סשן, או שהקונפיגורציה השתנתה	/reload-plugins או הפעלה מחדש; ודאו ב‑/mcp שהשרתים מופיעים
Permission denied על טבלה אחת בלבד	החיבור תקין, אבל ההרשאות של אותה טבלה לא כוללות את המשתמש — או שהטבלה נוצרה זה עתה ואין לה הרשאות כלל	ראו ניהול, מינוח ומכירות
שני סטים זהים של כלים	גם השרת של התוסף וגם שרת שרשמתם ידנית מחוברים	כבו את המיותר ב‑/mcp
הכלים עונים — אבל מהמערכת הלא נכונה	יותר מחיבור אחד פעיל, או שהאישורים שייכים לבסיס נתונים אחר	השאירו בדיוק שרת MyBusiness אחד פעיל; Get-Schema ואישור מול המשתמש
תוצאות ריקות במקום שבו יש נתונים	Get-Data מחזיר 5 שורות כברירת מחדל — תשובה קטומה נראית כמו טבלה קטנה	תמיד להעביר limit במפורש

אל תזהו כשל אימות לפי מחרוזת אחת

נוסח השגיאה שונה בין כלי לכלי על אותו מצב עצמו. קוד שמחפש טקסט שגיאה ספציפי כדי להחליט “האם אני מחובר” יישבר. אבחנו מהתשובה של כלי נתונים (Get-Data על טבלה אמיתית) — לא מקוד הסטטוס, לא מנורית החיבור ולא מ‑tools/list. פירוט: שרת ה‑MCP.

היגיינת מפתחות

• מפתח אחד לכל לקוח או מטרה. ביטול נקודתי הוא היתרון היחיד של המפתח על Master Key — הוא שווה משהו רק אם המפתחות אינם משותפים. זכרו את התקרה: עד 5 מפתחות לבסיס נתונים.
• בטלו ביציאה של אדם, בחשד, ובלוח זמנים קבוע.
• לעולם אל תדביקו מפתח לצ’אט, לקריאת שירות, למייל או ל‑repository.
• עובדים על מערכת של מישהו אחר? הוא מייצר את המפתח, והוא מבטל אותו כשהעבודה נגמרה.
• שם הכותרת קובע: שרת ה‑MCP מקבל את המפתח כ‑X-Parse-API-Key. תחת X-Parse-Master-Key הוא נחשב לפרטי גישה שגויים.

המשך

• אינדקס 22 הסקילים — מה הותקן לכם עכשיו
• עבודה בטוחה עם סוכן על מערכת חיה — לפני הכתיבה הראשונה לייצור
• שרת ה‑MCP — הפרוטוקול והכלים
• אימות והרשאות