מדריך קלוד קוד בעברית
לאתר הראשי כל המדריכים קלאודפלייר קלוד דסקטופ גרוק CLI גרוק בוט MCP קרסור וואטסאפ OpenClaw n8n בענן n8n בהתקנה עצמית

פרק 9

MCP: חיבור לכלים ולשירותים חיצוניים

פרוטוקול Model Context Protocol (MCP) הוא תקן פתוח לחיבור קלוד קוד לכלים חיצוניים, מסדי נתונים וממשקי API. במקום להעתיק נתונים לשיחה מכלי אחר, מחברים שרת וקלוד קורא ופועל מול המערכת ישירות.

אם זה השרת הראשון שלכם, התחילו ב-MCP quickstart. העמוד הזה הוא מדריך מעשי מלא, לפי התיעוד הרשמי מ-16 בספטמבר 2026.

[!WARNING] חברו רק שרת שאתם סומכים עליו. שרתים ששולפים תוכן חיצוני עלולים לחשוף אתכם לסכנת הזרקת פרומפט (prompt injection).

#מה אפשר לבקש אחרי החיבור

עם שרתי MCP מחוברים אפשר לבקש מקלוד קוד:

  • מימוש פיצ'רים מתוך מערכות מעקב אחר משימות: למשל לממש פיצ'ר לפי טיקט ב-Jira ולפתוח PR ב-GitHub.
  • ניתוח נתוני ניטור: לבדוק ב-Sentry וב-Statsig את השימוש בפיצ'ר.
  • תשאול מסדי נתונים: שליפת כתובות אימייל של 10 משתמשים אקראיים שהשתמשו בפיצ'ר מסוים, מתוך מסד נתוני PostgreSQL.
  • שילוב עיצובים: עדכון תבנית אימייל סטנדרטית לפי עיצוב חדש מ-Figma שפורסם ב-Slack.
  • אוטומציה של תהליכי עבודה: יצירת טיוטות ב-Gmail להזמנת אותם משתמשים לשיחת משוב על הפיצ'ר החדש.
  • תגובה לאירועים חיצוניים: שרת MCP יכול לשמש גם כערוץ (channel) שדוחף הודעות לסשן, כדי שקלוד יגיב להודעות Telegram, צ'אטים ב-Discord או אירועי webhook כשאתם לא ליד המחשב.

#איתור ובניית שרתים

חפשו מחברים שנבדקו ב-Anthropic Directory. אותה תשתית MCP משמשת גם את קלוד קוד, ולכן כל שרת מרוחק שמופיע שם ניתן להוספה בעזרת claude mcp add.

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

אפשר גם לבקש מקלוד להקים שלד של שרת עבורכם באמצעות התוסף הרשמי mcp-server-dev:

  1. התקנת התוסף: בתוך סשן קלוד קוד, הריצו:

    /plugin install mcp-server-dev@claude-plugins-official

    אם ההתקנה נכשלת, התאימו להודעה שקלוד קוד מדווח:

    • Marketplace "claude-plugins-official" not found: הוסיפו את שוק התוספים עם /plugin marketplace add anthropics/claude-plugins-official, ואז נסו שוב.
    • התוסף לא נמצא בשוק: בדקו ששם התוסף נכון.

    אם סיכום ההתקנה מדווח Run /reload-plugins to activate., קלוד קוד מריץ את הטעינה מחדש הזו עבורכם. אם הטעינה מחדש מתריעה שההודעה הבאה שלכם תקרא מחדש את השיחה, הריצו /reload-plugins --force.

  2. הרצת יכולת הבנייה:

    /mcp-server-dev:build-mcp-server

    קלוד ישאל על תרחיש השימוש ויבנה שלד לשרת HTTP מרוחק או לשרת stdio מקומי.

#התקנת שרתי MCP

אפשר להגדיר שרתי MCP בכמה דרכים לפי הצרכים שלכם:

#אפשרות 1: הוספת שרת HTTP מרוחק

שרתי HTTP הם האפשרות המומלצת לחיבור שרתי MCP מרוחקים, וזהו פרוטוקול התעבורה הנתמך ביותר בשירותי ענן.

# Basic syntax
claude mcp add --transport http <name> <url>

# Real example: Connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Example with Bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

בהגדרת שרתי MCP דרך JSON בקבצים .mcp.json, ~/.claude.json או בפקודה claude mcp add-json, השדה type מקבל גם streamable-http ככינוי ל-http. מפרט MCP משתמש בשם streamable-http לתעבורה זו, ולכן תצורות המועתקות מתיעוד של שרתים פועלות ללא שינוי.

רשומת JSON שמכילה url ללא type היא שגיאת תצורה, מכיוון שקלוד קוד קורא רשומה ללא type כשרת stdio. קלוד קוד מדלג על השרת ומדווח: MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry. לפני גרסה v2.1.202, קלוד קוד דיווח על שגיאה זו כ-command: expected string, received undefined.

בהרצות עם --output-format stream-json, קלוד קוד מדווח על רשומת --mcp-config שדולגה בשדה mcp_server_errors של אירוע system/init, כך שסקריפטים יכולים לזהות שהשרת לא נטען מעולם. הדבר דורש קלוד קוד מגרסה v2.1.219 ומעלה.

#אפשרות 2: הוספת שרת SSE מרוחק

[!WARNING] תעבורת SSE (Server-Sent Events) הוצאה משימוש. השתמשו בשרתי HTTP במקום זאת, כשהם זמינים.

שירותים מסוימים עדיין חושפים נקודת קצה של SSE בלבד. הוסיפו אותם בעזרת אותה פקודת claude mcp add --transport http <name> <url> כמו שרת HTTP. קלוד קוד מנסה קודם את תעבורת HTTP ועובר אוטומטית ל-SSE אם השרת אינו מקבל אותה. המעבר האוטומטי דורש קלוד קוד מגרסה v2.1.265 ומעלה.

בגרסה מוקדמת יותר, או כדי להתחבר ישירות מעל SSE, העבירו --transport sse:

# Basic syntax
claude mcp add --transport sse <name> <url>

# Real example: Connect to Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Example with authentication header
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

#אפשרות 3: הוספת שרת stdio מקומי

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

קלוד קוד מגדיר בסביבת תהליך השרת שנוצר את המשתנה CLAUDE_PROJECT_DIR עם שורש הפרויקט, כדי שהשרת יוכל לפתור נתיבים יחסיים לפרויקט בלי להסתמך על ספריית העבודה. זו אותה ספרייה ש-hooks מקבלים במשתנה CLAUDE_PROJECT_DIR שלהם. קראו אותו מתוך תהליך השרת, למשל process.env.CLAUDE_PROJECT_DIR ב-Node או os.environ["CLAUDE_PROJECT_DIR"] ב-Python.

CLAUDE_PROJECT_DIR הוא שורש פרויקט יציב ואינו משתנה כשמוסיפים או מסירים ספריות עבודה באמצע הסשן. שרת שמגביל את הגישה שלו למערכת הקבצים לקבוצה של ספריות מורשות צריך לממש את בקשת ה-MCP בשם roots/list. קלוד קוד עונה לבקשת roots/list עם ספריית ההפעלה של הסשן בתוספת כל ספריית עבודה נוספת שהענקתם עם --add-dir, /add-dir או ההגדרה additionalDirectories. קלוד קוד שולח התראה notifications/roots/list_changed כאשר קבוצה זו משתנה. לפני גרסה v2.1.203, roots/list החזיר רק את ספריית ההפעלה וקלוד קוד לא שלח את ההתראה notifications/roots/list_changed.

משתנה זה מוגדר בסביבת השרת ולא בסביבה של קלוד קוד עצמו, ולכן הפניה אליו באמצעות הרחבת ${VAR} ב-command או ב-args של רשומת .mcp.json בהיקף פרויקט, או של רשומת שרת בהיקף מקומי או משתמש ב-~/.claude.json, דורשת ערך ברירת מחדל כגון ${CLAUDE_PROJECT_DIR:-.}. תצורות MCP המסופקות על ידי תוספים מחליפות את ${CLAUDE_PROJECT_DIR} ישירות ואינן זקוקות לברירת מחדל.

# Basic syntax
claude mcp add [options] <name> -- <command> [args...]

# Real example: Add Airtable server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

[!IMPORTANT] הפרדת ארגומנטים של השרת באמצעות --

בשרתי stdio, הסימן -- מפריד בין האפשרויות של קלוד קוד עצמו, כגון --transport, --env ו---scope, לבין הפקודה והארגומנטים שמריצים את השרת. כל מה שמופיע אחרי -- מועבר לשרת ללא שינוי.

לדוגמה:

  • claude mcp add --transport stdio myserver -- npx server מריץ את npx server
  • claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080 מריץ את python server.py --port 8080 עם KEY=value בסביבה

ללא --, קלוד קוד ינסה לפענח את הדגלים של השרת, כמו --port לעיל, כאפשרויות שלו.

הדגל --env מקבל מספר זוגות של KEY=value. אם שם השרת מגיע ישירות אחרי --env, ה-CLI קורא את השם כזוג נוסף ודוחה אותו. מקמו לפחות אפשרות אחת אחרת, כגון --transport stdio, בין --env לשם השרת.

#אפשרות 4: הוספת שרת WebSocket מרוחק

שרתי WebSocket מחזיקים חיבור דו-כיווני קבוע, המתאים לשרתי MCP מרוחקים שדוחפים אירועים לקלוד ביוזמתם. השתמשו ב-HTTP במקום זאת כאשר השרת שלכם רק עונה לבקשות, מאחר ש-HTTP תומך ב-OAuth ובדגל claude mcp add --transport, בעוד ש-WebSocket אינו תומך באף אחד מהם.

הגדירו שרתי WebSocket ב-.mcp.json או בעזרת claude mcp add-json:

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

רשומת type: "ws" מקבלת את אותם שדות כמו http: url, headers, headersHelper, timeout ו-alwaysLoad. האימות מתבצע בכותרות בלבד, לכן העבירו טוקן סטטי ב-headers או צרו טוקן בזמן החיבור באמצעות headersHelper. הדגל claude mcp add --transport אינו מקבל ws.

#הוספה מהוראות של לקוח אחר

שרתי MCP אינם ייעודיים לקלוד קוד בלבד, ולכן הוראות התקנה של שרת מסוים עשויות להיכתב עבור Claude Desktop, Cursor או לקוח MCP אחר, ללא פקודת claude mcp add. כדי להוסיף את השרת בכל זאת, חפשו בהוראות את אחד משלושת הדברים הבאים:

  • כתובת URL, כגון https://mcp.example.com/mcp: השרת מרוחק.
  • פקודת הפעלה, כגון npx -y @example/mcp-server: השרת רץ על המחשב שלכם.
  • בלוק JSON של mcpServers: תצורה שנכתבה עבור קובץ הגדרות של לקוח אחר.

כל אחד מהם הוא אחד הקלטים שארבע האפשרויות בהתקנת שרתי MCP מקבלות. מצאו את המבנה שבידיכם כדי להמירו לפקודה שקלוד קוד מקבל. כל פקודה נכתבת להיקף מקומי (local) אלא אם תוסיפו --scope project או --scope user.

#מכתובת URL

כתובת URL מעידה על שרת מרוחק. עבור נקודת קצה של https://, הוסיפו אותה עם --transport http, או פעלו לפי אפשרות 2 כאשר ההוראות מציינות שנקודת הקצה משתמשת ב-SSE. עבור נקודת קצה של wss://, השתמשו באפשרות 4, מכיוון ש---transport אינו מקבל ws:

claude mcp add --transport http example https://mcp.example.com/mcp

אם ההוראות מספקות גם מפתח API או כותרת טוקן, העבירו אותם עם --header כפי שמוצג באפשרות 1.

#מפקודת npx, uvx או בינארי

פקודת הפעלה מעידה שהשרת רץ כתהליך stdio מקומי. שימו את כל הפקודה אחרי --, כדי שקלוד קוד יעביר דגלים כמו -y לפקודה שמפעילה את השרת במקום לפענח אותם כאפשרויות שלו. העבירו משתני סביבה שההוראות דורשות באמצעות --env, אחרי שם השרת ולפני --:

claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server

אפשרות 3 מכסה את מפריד ה--- במלואו.

#מבלוק JSON של mcpServers

בלוק mcpServers שנכתב עבור לקוח MCP אחר, כמו Claude Desktop, משתמש במבנה שקלוד קוד קורא. העבירו ל-claude mcp add-json את האובייקט הפנימי שבתוך mcpServers, ולא את המעטפת החיצונית. יש לבצע שני תיקונים תחילה במידת הצורך:

  • ערך url ללא type: הוסיפו "type": "http", "type": "sse" או "type": "ws" בהתאמה לנקודת הקצה. קלוד קוד קורא רשומה ללא type כשרת stdio, ולכן רשומת url ללא type תיכשל.
  • שם מפתח עם תווים שאינם אותיות, מספרים, מקפים וקווים תחתונים: בחרו שם שרת המשתמש בתווים אלה בלבד. אחרת, המפתח משמש כשם השרת.

לדוגמה, הבלוק הבא:

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

הופך לפקודה זו:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

כדי לשתף את השרת עם הצוות שלכם במקום זאת, הוסיפו --scope project, או הוסיפו את הרשומה תחת mcpServers בקובץ .mcp.json בשורש הפרויקט ובצעו commit.

כל פקודת claude mcp add ו-claude mcp add-json מדפיסה שורת Added .... כדי לוודא שקלוד קוד התחבר, הריצו claude mcp get <name>.

#ניהול שרתים בטרמינל ובסשן

לאחר ההגדרה, ניתן לנהל את שרתי ה-MCP באמצעות הפקודות הבאות:

פקודהפעולה
claude mcp listהצגת כל השרתים המוגדרים ומצב הבריאות לצד כל אחד
claude mcp get <name>קבלת פרטים עבור שרת ספציפי
claude mcp remove <name>הסרת שרת
/mcpבתוך סשן קלוד קוד: בדיקת סטטוס השרת, אימות וחיבור
claude mcp login <name>הרצת תהליך אימות OAuth ישירות מהמעטפת
claude mcp logout <name>מחיקת פרטי אימות שמורים עבור השרת
claude mcp reset-project-choicesאיפוס בחירות האישור עבור שרתי פרויקט מ-.mcp.json

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

#מצבי שרתים ופירוט שגיאות

הפקודה claude mcp add מאשרת הוספה מוצלחת בהדפסת שורת Added ..., כלומר התצורה נכתבה. הפקודה claude mcp list מציגה סטטוס בריאות לצד כל שרת ברשימה:

  • ✔ Connected: מוכן לשימוש.
  • ! Connected · tools fetch failed: השרת התחבר אך לא הצליח לרשום את כליו. הריצו claude mcp get <name> לפרטי השגיאה.
  • ! Needs authentication: השרת נגיש אך דורש כניסה בדפדפן, או טוקן שמועבר עם --header.
  • ✘ Failed to connect: השרת לא הגיב. סטטוס כשל מעיד שקלוד קוד לא הצליח להתחבר לאותו שרת, ולא שפקודת הרשימה נכשלה.
  • ✘ Connection error: ניסיון החיבור נתקל בשגיאה.

בקונסולות ישנות מסוימות של Windows מוצגים הסימנים √ ו-× במקום ✔ ו-✘.

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

מצבמשמעות
⏸ Pending approval (run claude to approve)שרת בהיקף פרויקט מתוך .mcp.json שעדיין לא אישרתם. מוצג הן ב-claude mcp list והן ב-claude mcp get <name>. יש להריץ claude באופן אינטראקטיבי כדי לבדוק ולאשר
✘ Rejected (see disabledMcpjsonServers in settings)שרת מ-.mcp.json שנדחה על ידי רשומת disabledMcpjsonServers. מוצג רק ב-claude mcp get <name>
⊘ Disabled for this project (re-enable via /mcp)שרת המופיע ברשימת disabledMcpServers של הפרויקט. מוצג הן ב-claude mcp list והן ב-claude mcp get <name>. הפעילו מחדש דרך לוח /mcp. לפני גרסה v2.1.238 שתי הפקודות התחברו לשרת מושבת כדי לבדוק בריאות

שרתי WebSocket אינם מופיעים בפלט של claude mcp list. השתמשו ב-claude mcp get <name> או בלוח /mcp כדי לבדוק אותם.

#אישורי שרתי פרויקט ואמון בסביבת העבודה

החל מגרסה v2.1.196, הפקודות claude mcp list ו-claude mcp get קוראות אישורי .mcp.json אך ורק מקובצי הגדרות שאינם שמורים במאגר ה-git, עד שתאשרו אמון בסביבת העבודה בהרצת claude ואישור תיבת דו-שיח של אמון סביבת העבודה. מאגר משוכפל אינו יכול לאשר את שרתיו בעצמו: הגדרות enableAllProjectMcpServers או enabledMcpjsonServers שנשמרו בתוך .claude/settings.json של הפרויקט מבוטלות בתיקייה שאינה מהימנה, והשרת נשאר במצב ⏸ Pending approval במקום להתחבר ולהיבדק.

אישורים מהמקורות הבאים עדיין חלים בתיקייה שאינה מהימנה:

  • קובץ ההגדרות של המשתמש ב-~/.claude/settings.json
  • הגדרות מנוהלות (managed settings)
  • הגדרות שהועברו עם הדגל --settings

קלוד קוד מחיל גם אישורים מקובץ .claude/settings.local.json שאינו במעקב git, אך הוא מריץ git כדי לבדוק האם הקובץ במעקב, והוא מבצע בדיקה זו רק בתיקייה מהימנה. בתיקייה שמעולם לא הוגדרה כמהימנה, קלוד קוד ממתין לאישור תיבת הדו-שיח של האמון לפני החלת אישורי הקובץ, אלא אם התיקייה היא תיקיית התצורה האישית שלכם: תיקיית הבית שלכם, או תיקייה שמוגדרת כ-CLAUDE_CONFIG_DIR. לפני גרסה v2.1.207, קלוד קוד החיל אישורים מקובץ .claude/settings.local.json שאינו במעקב גם בתיקייה שמעולם לא הוגדרה כמהימנה.

רשומת disabledMcpjsonServers בכל קובץ הגדרות עדיין דוחה את השרת.

#פרטי סטטוס שרת

בלוח /mcp, כולל תפריט השרת שם, ובמנהל התוספים /plugin, שרת HTTP או SSE מרוחק שהשתמשתם בו בעבר עשוי להציג סטטוס cached, למשל cached 2h ago · connects on first use · 5 tools. קלוד קוד טוען את רשימת הכלים של השרת מתוך מטמון הגילוי (discovery cache) שנשמר מסשן קודם במקום להתחבר בעת ההפעלה, ומתחבר לשרת רק בפעם הראשונה שקלוד קורא לאחד מכליו. הכלים זמינים כבר מההודעה הראשונה שלכם, כך שאין צורך לעשות דבר. מטמון הגילוי וסטטוס cached דורשים קלוד קוד מגרסה v2.1.221 ומעלה.

מטמון הגילוי כבוי כברירת מחדל אלא אם הופעל עבור חשבונכם בהשקה הדרגתית. הגדירו את משתנה הסביבה MCP_DISCOVERY_CACHE=1 כדי להפעילו, או 0 כדי להשאירו כבוי גם אם ההשקה הפעילה אותו. לפני גרסה v2.1.238, המטמון היה פעיל כברירת מחדל.

שתי פעולות בתפריט שרת בלוח /mcp משפיעות גם הן על רשומת המטמון של אותו שרת:

  • Reconnect: עבור שרת במצב cached, קלוד קוד מתחבר אליו מיד במקום בקריאת הכלי הראשונה ושומר על הרשומה. עבור שרת מחובר או שנכשל, קלוד קוד מתחבר מחדש ומוחק את הרשומה.
  • Clear authentication: קלוד קוד מבטל את אימות השרת ומוחק את הרשומה.

לאחר מחיקת הרשומה, קלוד קוד מושך את רשימת הכלים ישירות מהשרת במקום מהמטמון.

כאשר סטטוס השרת הוא ✘ Failed to connect, הפקודה claude mcp list מצרפת את פרטי הכשל לשורת הסטטוס, ו-claude mcp get <name> מציגה אותם בשורת Issue:: קוד הסטטוס ב-HTTP או קוד השגיאה, בתוספת כל טקסט שגיאה שהשרת החזיר. תצוגת הפרטים ב-/mcp כוללת את אותו טקסט בשורת Issue:. קלוד קוד מצנזר טקסט שנראה כמו פרטי אימות ולעולם אינו כולל את כתובת ה-URL המורחבת של השרת, אשר עלולה להכיל סודות. קלוד קוד אינו מצרף פירוט לסטטוס ✘ Connection error, מכיוון שטקסט החריגה עלול להכיל כתובת זו. לפני גרסה v2.1.219, שתי הפקודות הציגו רק סטטוס כשל בסיסי ללא קוד או טקסט שגיאה.

כאשר משלימים אימות מתוך /mcp והחיבור עדיין נכשל עם קוד סטטוס HTTP או שגיאת תעבורה, קלוד קוד מוסיף את הקוד הזה ואת מקור ה-URL של השרת (Origin: סכמה ומארח, בתוספת הפורט אם מוגדר, למשל https://mcp.example.com) להודעה המודפסת לאחר הניסיון:

  • הנתיב והשאילתה אינם מופיעים לעולם בהודעה זו.
  • עבור שרת בהיקף מקומי, פרויקט או משתמש, או בתצורת MCP מנוהלת, המקור מציג את המארח כפי שנכתב בתצורה, כך שהפניה ל-${VAR} במארח אינה מורחבת בהודעה.
  • בכשל ללא קוד סטטוס או קוד שגיאה, קלוד קוד מציג את טקסט השגיאה ללא המקור.

שרת מרוחק שהתצורה שלו כוללת url ריק מוצג כ-not configured ב-/mcp, ב-claude mcp list ובמנהל /plugin, וקלוד קוד אינו מנסה להתחבר אליו. תוסף יכול לכלול רשומת מציין מקום כזו עבור מחבר שיוגדר בהמשך, ולכן קלוד קוד אינו מדווח עליה כשגיאה או כבעיית התקנה. תצוגת הפרטים ב-/mcp מציינת No URL configured for this server. הגדירו את ערך url של הרשומה כדי לחבר אותה. לפני גרסה v2.1.208, קלוד קוד דיווח על url ריק כבעיית תצורה עם בקשה להתחבר מחדש.

#אזהרות תצורה

קלוד קוד מתריע על בעיות התצורה הבאות בפלט claude mcp list ובתוך /mcp:

  • רווחים נסתרים (Hidden whitespace): רווחים או ירידות שורה בתחילת או בסוף ערכי תצורה, שלרוב נובעים מהדבקת טוקן עם תו שורה חדשה בסופו. קלוד קוד בודק את command, url, כל איבר במערך args, ואת המפתחות והערכים תחת env ו-headers. ההתראה מציינת את השדות המושפעים ללא חשיפת ערכם, למשל Leading or trailing whitespace in: headers.Authorization. קלוד קוד אינו חותך את הרווחים ומשתמש בערכים בדיוק כפי שנכתבו, לכן יש לערוך את התצורה כדי להסיר אותם.
  • אותו שם ביותר מהיקף אחד: אם מגדירים את אותו שם שרת ביותר מהיקף אחד עם נקודות קצה שונות, קלוד קוד מתריע על ההתנגשות בפלט claude mcp list וב-/mcp. קלוד קוד שומר התחברויות OAuth לפי נקודת קצה, כך שאימות של הגדרה אחת בפרויקט מסוים לא ימנע צורך באימות נפרד בפרויקט שבו נטענת הגדרה אחרת. שמרו על נקודת הקצה הרצויה והסירו את האחרות באמצעות claude mcp remove <name> --scope <scope>. בהתראה זו נקודות הקצה מצוטטות כפי שנכתבו בתצורה ללא הרחבת משתני ${VAR}, כך שערכים רגישים אינם נחשפים.
  • שמות שמורים: קלוד קוד שומר לעצמו את השמות של השרתים המובנים שלו, כולל workspace, claude-in-chrome, computer-use, Claude Preview ו-Claude Browser. אם תצורתכם מגדירה שרת עם שם שמור, קלוד קוד מדלג עליו בעת הטעינה ומציג אזהרה המבקשת לשנות את שמו. הפקודה claude mcp add דוחה שם שמור עם שגיאה. השמות Claude Preview ו-Claude Browser שניהם שמות של השרת המובנה המשמש את חלונית התצוגה המקדימה באפליקציית שולחן העבודה של קלוד קוד. לפני גרסה v2.1.205, השם Claude Browser לא היה שמור, ושרת שהוגדר על ידי משתמש יכול היה להירשם בשם זה.
  • משתנה סביבה חסר: אם הפניה ל-${VAR} בתצורת שרת מציינת משתנה שאינו מוגדר ואין לו ערך ברירת מחדל :-default, קלוד קוד מתריע בפלט claude mcp list וב-/mcp, תוך ציון שם המשתנה, ועדיין טוען את השרת עם הטקסט ${VAR} ללא הרחבה. הגדירו את המשתנה או הוסיפו ערך ברירת מחדל ${VAR:-default}. ב-url וב-headers של שרת מרוחק, משתני פרטי אימות מסוימים נקראים כריקים במקום זאת, ללא אזהרה.

#זמינות כלים

לוח /mcp מציג את מספר הכלים לצד כל שרת מחובר, ומסמן שרתים שמצהירים על יכולת כלים אך אינם חושפים אף כלי בפועל.

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

  • עם חיפוש כלים (tool search), מצב ברירת המחדל: ההמתנה מתבצעת בתוך הקריאה לכלי ToolSearch.
  • ללא חיפוש כלים: קלוד משתמש בכלי WaitForMcpServers במקום זאת. תצורות ללא חיפוש כלים כוללות שימוש ב-ANTHROPIC_BASE_URL מותאם אישית, הגדרת ENABLE_TOOL_SEARCH=false, או שימוש במודל קודם לדור Claude 4.5 ב-Agent Platform של Google Cloud.
  • בפריסת Microsoft Foundry המתארחת ב-Azure: קלוד מתחיל במסלול חיפוש הכלים ולא עם WaitForMcpServers, מכיוון שקלוד קוד מזהה את הדחייה בצד השרת רק מתוך ה-API. לאחר שקלוד קוד מעביר פריסה זו לטעינה מראש (upfront), כלים משרת שמסיים להתחבר הופכים לזמינים בבקשה הבאה של קלוד.

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

#השבתת שרת ללא הסרתו

העבירו שרת למצב כבוי בלוח /mcp כדי למנוע מקלוד קוד להתחבר אליו, מבלי לאבד את התצורה שלו. קלוד קוד עדיין יציג את השרת ב-/mcp, כשהוא מסומן כמושבת.

בעת שינוי מצב שרת, קלוד קוד שומר את בחירתכם לפי פרויקט ב-~/.claude.json, באחת משתי רשימות המכסות קבוצות שרתים נפרדות לחלוטין:

  • disabledMcpServers: רשימת ביטול (opt-out) עבור שרתים שהוגדרו על ידי משתמש, שרתי תוספים, שרתים שהארגון מספק דרך הגדרות מנוהלות, מחברי claude.ai שקלוד קוד מושך בעצמו, ושרתים מובנים שמופעלים כברירת מחדל. קלוד קוד אינו מתחבר לשרת המופיע ברשימה זו. כאשר משביתים מחבר claude.ai באמצעות מתג /mcp של הפרויקט, קלוד קוד כותב אותו לרשימה זו תחת שם התצוגה שלו, למשל claude.ai Slack.
  • enabledMcpServers: רשימת הפעלה (opt-in) עבור שרתים מובנים שמוגדרים ככבויים כברירת מחדל, כגון computer-use. קלוד קוד מתחבר לשרת כזה רק אם ציינתם אותו ברשימה זו.

קלוד קוד בודק בדיוק אחת משתי הרשימות עבור כל שרת, ולכן אף רשימה אינה דורסת את האחרת. אם תוסיפו שרת רגיל ל-enabledMcpServers, או שרת מובנה כבוי ל-disabledMcpServers, קלוד קוד יתעלם מהרשומה.

רשימות אלו אינן קשורות ל-enabledMcpjsonServers ול-disabledMcpjsonServers, השולטות באישור שרתים המוגדרים בקובץ .mcp.json של הפרויקט.

#סביבות ריצה של לקוח MCP

קלוד קוד מתחבר לשרתי MCP דרך אחת משתי סביבות ריצה של לקוח. סביבת v1 בנויה על MCP TypeScript SDK 1.x. סביבת v2 מבוססת על MCP TypeScript SDK 2.0, המוסיף תמיכה ברוויזיית פרוטוקול MCP מתאריך 2026-07-28. שאר המדריך חל על שתי סביבות הריצה, למעט מקומות המציינים במפורש את v2.

קלוד קוד בוחר סביבת ריצה בכל הפעלה ושומר עליה עד היציאה. בסשנים שבהם הוא מושך דגלי פיצ'רים (feature flags), הוא משתמש בסביבת v2 החל מגרסה v2.1.232 ומעלה.

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

  • סשנים ב-Amazon Bedrock, Claude Platform ב-AWS, Google Cloud Agent Platform או Microsoft Foundry, אלא אם פלטפורמת האירוח מגדירה את CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST.
  • סשנים שהתחברו דרך Claude apps gateway.
  • סשנים שבהם כיביתם טלמטריה או משיכת דגלי פיצ'רים, למשל באמצעות DISABLE_TELEMETRY.

בסביבת v2, קלוד קוד גם:

  • שואל שרתי HTTP האם הם תומכים ברוויזיה החדשה, ומשתמש בה מול אלה שתומכים. הוא שואל גם שרתי מחברים של claude.ai בסשנים שבהם הוא מושך דגלי פיצ'רים. כדי לגרום לו לשאול שרתי stdio, או שרתי מחברים בכל סשן, הגדירו את MCP_PROTOCOL_NEGOTIATION ל-auto. הוא מתחבר לכל שאר השרתים כפי ש-v1 עושה.
  • מקבל התראות list_changed משרתים ברוויזיה החדשה על גבי זרם (stream) שהוא מחזיק פתוח.
  • אינו רושם שרת ערוץ (channel) שמתחבר ברוויזיה החדשה, מכיוון שרוויזיה זו אינה יכולה להעביר הודעות ערוץ.
  • מכשיל התחברות MCP OAuth שתגובת ההרשאה שלה מציינת מנפיק (issuer) בלתי צפוי.

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

לבחירת סביבת הריצה בעצמכם, הגדירו את MCP_SDK_GENERATION ל-v1 או v2. כדי לקבוע אם קלוד קוד ינהל משא ומתן על הפרוטוקול, הגדירו את MCP_PROTOCOL_NEGOTIATION ל-auto או legacy.

#עדכוני כלים דינמיים

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

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

#הזרמת התראות בסביבת ריצה v2

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

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

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

#חיבור מחדש אוטומטי

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

#ניתוק של שרת מרוחק באמצע סשן

קלוד קוד מתחבר מחדש לשרת מרוחק שנותק תוך שימוש בנסיגה מעריכית (exponential backoff): עד חמישה ניסיונות, החל מהשהיה של שנייה אחת המוכפלת בכל פעם. אופן התצוגה תלוי באופן הרצת קלוד קוד:

  • בסשן אינטראקטיבי: לוח /mcp מציג את השרת במצב המתנה (pending) בזמן שקלוד קוד מתחבר מחדש. לאחר חמישה כישלונות, קלוד קוד מסמן את השרת כנכשל, או כדורש אימות אם השרת דורש הרשאה מחדש. כאשר השרת מסומן כנכשל, מופיעה התראה MCP server "<name>" disconnected · open /mcp to reconnect. ניתן לנסות שוב ידנית מתוך /mcp.
  • בהרצות claude -p ובסשנים של Agent SDK: קלוד קוד מתחבר מחדש לפי אותו לוח זמנים, ללא לוח /mcp להצגת הניסיונות.

#כישלון בחיבור ראשון

כאשר חיבור ראשון לשרת HTTP או SSE נכשל עקב שגיאה זמנית, כגון תגובת 5xx, סירוב חיבור (connection refused) או פסק זמן (timeout), קלוד קוד מנסה שוב עד שלוש פעמים. אם החיבור עדיין נכשל, קלוד קוד מסמן את השרת כנכשל. ניסיונות חוזרים אלה חלים בהפעלת התוכנה, בהוספת שרת באמצע סשן, בסשן ענן (cloud session), ובהוספת שרת דרך setMcpServers() ב-Agent SDK.

קלוד קוד אינו מבצע ניסיונות חוזרים במקרים הבאים:

  • חיבור ראשון לשרת WebSocket.
  • שגיאת אימות או שגיאת 404 (Not Found), מכיוון שהן דורשות שינוי תצורה לפתרונן. עם זאת, כאשר headersHelper הוא המקור היחיד של כותרת Authorization עבור השרת, קלוד קוד מנסה שוב גם בשגיאת אימות, מכיוון שהוא מריץ את ה-helper מחדש בכל ניסיון ויכול לקבל פרטי אימות עדכניים.

#כישלון בבקשות גילוי

לאחר שהשרת מתחבר, קלוד קוד שולח לו בקשות לגילוי יכולות כגון tools/list, prompts/list ו-resources/list. קלוד קוד מנסה לשלוח בקשות אלו שוב עד שלוש פעמים עם השהיה קצרה בעת שגיאת רשת או שרת זמנית. הוא אינו מנסה שוב בשגיאות אימות, תגובות 4xx או פקיעת תוקף של בקשה (timeouts).

#איך קלוד לומד ששרת נכשל

האם קלוד קוד מדווח לקלוד על שרת מוגדר שנכשל בחיבור תלוי במצב חיפוש הכלים (tool search), שמופעל כברירת מחדל:

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

#דחיפת הודעות באמצעות ערוצים

שרת MCP יכול גם לדחוף הודעות ישירות לתוך הסשן שלכם, כך שקלוד יוכל להגיב לאירועים חיצוניים כמו תוצאות CI, התראות ניטור או הודעות צ'אט. כדי להפעיל זאת, השרת מצהיר על יכולת claude/channel ואתם מפעילים אותה עם הדגל --channels בהפעלת קלוד קוד.

בסביבת ריצה v2, אם הגדרתם את MCP_PROTOCOL_NEGOTIATION ל-auto ושרת ערוץ ניהל משא ומתן על רוויזיית פרוטוקול MCP מתאריך 2026-07-28, הוא אינו יכול להעביר הודעות ערוץ, ולכן קלוד קוד אינו רושם אותו כערוץ. השארת המשתנה ריק, או הגדרתו ל-legacy, שומרת שרתי stdio על לחיצת היד הקודמת.

#מגבלות זמן וזמני המתנה של כלים

טיפים ודגלים חשובים לניהול תצורה וזמנים:

  • הדגל -s או --scope קובע היכן נשמרת התצורה: local (ברירת מחדל, לפרויקט הנוכחי בלבד), project (משותף דרך .mcp.json), או user (גלובלי לכל הפרויקטים).
  • הגדרת משתני סביבה מתבצעת עם -e או --env (למשל -e KEY=value).
  • הדגלים --transport ו---header מקבלים גם קיצורים: -t ו--H.
  • משך הזמן המרבי להפעלת שרת MCP נקבע על ידי משתנה הסביבה MCP_TIMEOUT (למשל MCP_TIMEOUT=10000 claude מגדיר פסק זמן של 10 שניות).
  • ניתן לקבוע מגבלת זמן להרצת כלים פר שרת על ידי הוספת שדה timeout במילישניות ברשומת השרת ב-.mcp.json, למשל "timeout": 600000 עבור 10 דקות. שדה זה גובר על משתנה הסביבה MCP_TOOL_TIMEOUT עבור אותו שרת בלבד.
  • קלוד קוד מציג אזהרה כאשר פלט כלי MCP חורג מ-10,000 טוקנים ומגביל את הפלט ל-25,000 טוקנים כברירת מחדל. להגדלת המגבלה, הגדירו את משתנה הסביבה MAX_MCP_OUTPUT_TOKENS (למשל MAX_MCP_OUTPUT_TOKENS=50000); סף האזהרה קבוע.
  • השתמשו ב-/mcp כדי לבצע אימות מול שרתים מרוחקים הדורשים אימות OAuth 2.0.

שדה timeout פר שרת הוא מגבלת זמן קשיחה (wall-clock) לכל קריאת כלי, והתראות התקדמות מהשרת אינן מאריכות אותו. ערכים מתחת ל-1000 מילישניות אינם נחשבים וחוזרים לערך של MCP_TOOL_TIMEOUT, או לברירת המחדל שלו של כ-28 שעות כאשר המשתנה אינו מוגדר. עבור שרתי HTTP, SSE או מחברי claude.ai, קיים גם טיימר שני פר בקשה המכסה כל בקשה עד לבייט התגובה הראשון של השרת. קלוד קוד קובע טיימר זה לגדול מבין שלושה ערכים: 60 שניות, מגבלת זמן הכלים החלה על השרת, ו-MCP_TIMEOUT. ברירת המחדל של 28 שעות כאשר MCP_TOOL_TIMEOUT אינו מוגדר אינה נכללת בהשוואה זו, וערך נמוך מ-60 שניות אינו מקצר את הטיימר. לשרתי stdio ו-WebSocket אין טיימר פר בקשה.

הגדרת timeout פר שרת של 1000 מילישניות ומעלה משמשת גם כרצפה לזמן ההמתנה לחוסר פעילות (idle timeout): קלוד קוד לעולם לא יבטל קריאת כלי של שרת זה עקב חוסר פעילות מוקדם יותר מאותו timeout. הדבר דורש קלוד קוד מגרסה v2.1.203 ומעלה.

קריאת כלי לשרת MCP שאינו שולח תגובה ואינו שולח התראת התקדמות במהלך חלון חוסר הפעילות מבוטלת עם שגיאה במקום להמתין למגבלה הקשיחה. זמן המתנה זה לחוסר פעילות דורש גרסה v2.1.187 ומעלה, וחל על כל סוגי השרתים למעט שרתי IDE ושרתי SDK בתוך התהליך. ברירת המחדל לחלון חוסר פעילות היא 5 דקות עבור שרתי HTTP, SSE, WebSocket ומחברי claude.ai, ו-30 דקות עבור שרתי stdio. לפני גרסה v2.1.203, שרתי stdio היו פטורים מזמן המתנה לחוסר פעילות.

הגדירו את משתנה הסביבה CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT במילישניות כדי לשנות חלון זה, או הגדירו אותו כ-0 כדי לבטל את הבדיקה.

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

#העברה אוטומטית לרקע של קריאות כלים ארוכות

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

המשימה מופיעה בפקודה /tasks, שבה ניתן גם לעצור אותה, והיא אינה שורדת יציאה מהסשן. המגבלות פר קריאה עדיין חלות בזמן שהיא רצה ברקע: מגבלת הזמן הקשיחה שנקבעה על ידי timeout פר שרת או MCP_TOOL_TIMEOUT, וזמן ההמתנה לחוסר פעילות שנקבע על ידי CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT.

הגדירו את משתנה הסביבה CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS במילישניות כדי לשנות את הסף, או קבעו אותו כ-0 כדי לבטל העברה אוטומטית לרקע. הגדרת CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 מבטלת זאת גם כן, יחד עם כל שאר תכונות משימות הרקע.

קריאות מסוימות אינן מועברות לעולם לרקע:

  • קריאות מתוך תתי סוכנים (subagents), שכן קלוד קוד מעביר לרקע רק קריאות מהשיחה הראשית.
  • קריאות לשרתי IDE.
  • קריאות במצב לא אינטראקטיבי (headless), אלא אם CLAUDE_AUTO_BACKGROUND_TASKS מוגדר כ-1, מכיוון שהרצה חד-פעמית עשויה להסתיים לפני קבלת התוצאה.
  • קריאה הממתינה לתיבת דו-שיח פתוחה של בקשת מידע (elicitation), מכיוון שהשרת חסום בהמתנה לקלט שלכם ולא איטי בפעולתו. קלוד קוד דוחה את ההעברה לרקע עד לסגירת תיבת הדו-שיח.

#שרתי MCP המסופקים על ידי תוספים

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

כיצד פועלים שרתי MCP של תוספים:

  • תוספים מגדירים שרתי MCP בקובץ .mcp.json בשורש התוסף או ישירות בתוך plugin.json.
  • כאשר מפעילים תוסף, קלוד קוד מפעיל את שרתי ה-MCP שלו אוטומטית.
  • קלוד קוד מציע את כלי ה-MCP של התוסף לצד כלים שהוגדרו ידנית.
  • הוספה והסרה של שרתי תוספים מתבצעת על ידי התקנה או הסרה של התוסף, ולא באמצעות פקודות /mcp. עדיין ניתן להשבית שרת תוסף מותקן דרך /mcp, מה שמונע מקלוד קוד להתחבר אליו מבלי להסיר את התוסף.

דוגמת תצורת MCP בתוסף:

בקובץ .mcp.json בשורש התוסף:

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

או בתוך plugin.json:

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

תכונות של שרתי MCP בתוספים:

  • מחזור חיים אוטומטי: שרתים מתחברים ומתנתקים בנקודות הבאות:
    • בהפעלת הסשן, קלוד קוד מתחבר אוטומטית לשרתים של תוספים מופעלים. ב-/mcp, שרת תוסף מרוחק (HTTP או SSE) שהשתמשתם בו בעבר יכול להציג סטטוס cached, וקלוד קוד יתחבר אליו כאשר קלוד יקרא לראשונה לאחד מכליו.
    • אם תפעילו או תשביתו תוסף במהלך סשן, קלוד קוד יחבר או ינתק את שרתי ה-MCP שלו בעת החלת השינוי. בסשן ללא טרמינל אינטראקטיבי, /reload-plugins אינו מחבר או מנתק שרתי MCP של תוספים, והשינויים ייכנסו לתוקף בסשן הבא.
    • בעת טעינה מחדש, קלוד קוד שומר על החיבורים החיים של שרתי תוספים שתצורתם לא השתנתה, ופועל כך גם בעת החלפת רשימת שרתי ה-MCP של הסשן דרך ה-Agent SDK מבלי לציין את שמם.
    • בעת מעבר תיקייה עם /cd בסשן (בגרסה v2.1.246 ומעלה), קלוד קוד מחבר את שרתי התוספים שההגדרות בתיקייה החדשה מפעילות, ומנתק שרתים של תוספים שאינם מופעלים עוד, ללא צורך בהרצת /reload-plugins לאחר המעבר.
    • בסשנים בענן (cloud sessions), קריאת MCP לשרת תוסף שטרם התחבר, למשל מיד לאחר התעוררות סשן שהיה בחוסר פעילות, מפעילה את השרת לפי דרישה וממתינה לחיבורו.
  • מצייני מקום של נתיבים: ${CLAUDE_PLUGIN_ROOT} מצביע על ספריית ההתקנה של התוסף, ${CLAUDE_PLUGIN_DATA} על ספריית המצב הקבוע שלו, ו-${CLAUDE_PROJECT_DIR} על שורש הפרויקט היציב. החלפה זו חלה על:
    • שרתי stdio: בשדות command, args, env.
    • שרתי http, sse ו-ws: בשדות url, headers ו-headersHelper. לפני גרסה v2.1.195, headersHelper העביר את מציין המקום כמחרוזת מילולית.
  • גישה לסביבת המשתמש: גישה לאותם משתני סביבה כמו שרתים שהוגדרו ידנית.
  • מספר סוגי תעבורה: תמיכה בתעבורת stdio, sse, http ו-ws, אם כי תמיכת התעבורה עשויה להשתנות לפי שרת.

שרתי תוספים מופיעים ב-/mcp עם סימון המעיד על כך שמקורם בתוספים.

שמות כלי MCP מתוספים:

כלים משרת MCP שמקורו בתוסף כוללים גם את שם התוסף וגם את מפתח השרת בשמם המלא: mcp__plugin_<plugin-name>_<server-name>__<tool-name>, כאשר כל תו שאינו באותיות אנגליות, ספרות, מקף או קו תחתון מוחלף בקו תחתון _. עבור שרת database-tools בתוסף my-plugin, כלי בשם query ייקרא כך:

mcp__plugin_my-plugin_database-tools__query

השתמשו בשם מלא זה בעת הפניה לכלי בכללי הרשאות, ברשימת allowed-tools של מיומנות (skill), בשדה tools של תת-סוכן, או בהתאמת הוקים (hooks). התאמת הוק שנכתבה מול שם השרת בלבד, כגון mcp__database-tools__.*, לא תופעל לעולם עבור שרת המסופק על ידי תוסף.

השרת עצמו נרשם תחת השם plugin:<plugin-name>:<server-name>, למשל plugin:my-plugin:database-tools. השתמשו בשם זה במקומות שבהם נדרש שם שרת, כגון שדה server בהוק מסוג mcp_tool.

#היקפי התקנה של MCP

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

היקףנטען במשותף עם הצוותנשמר ב
localהפרויקט הנוכחי בלבדלא~/.claude.json
projectהפרויקט הנוכחי בלבדכן, דרך בקרת גרסאות.mcp.json בשורש הפרויקט
userכל הפרויקטים שלכםלא~/.claude.json

#היקף מקומי

היקף מקומי הוא ברירת המחדל. שרת בהיקף מקומי נטען רק בפרויקט שבו הוספתם אותו ונשאר פרטי עבורכם. קלוד קוד שומר אותו ב-~/.claude.json תחת נתיב הפרויקט, כך שהוא לא יופיע בפרויקטים אחרים. השתמשו בהיקף מקומי לשרתי פיתוח אישיים, תצורות ניסיוניות או שרתים עם פרטי אימות שאינכם רוצים לשמור בבקרת גרסאות.

[!NOTE] המונח "היקף מקומי" עבור שרתי MCP שונה מהגדרות מקומיות כלליות: שרתי MCP בהיקף מקומי נשמרים ב-~/.claude.json (בספריית הבית), בעוד שהגדרות מקומיות כלליות נשמרות בקובץ .claude/settings.local.json (בספריית הפרויקט).

# Add a local-scoped server (default)
claude mcp add --transport http stripe https://mcp.stripe.com

# Explicitly specify local scope
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

הפקודה כותבת את הגדרת השרת תחת הפרויקט הנוכחי בתוך ~/.claude.json:

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

#היקף פרויקט

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

# Add a project-scoped server
claude mcp add --transport http shared-server --scope project https://example.com/mcp

קובץ .mcp.json שנוצר משתמש במבנה אחיד:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

מטעמי אבטחה, קלוד קוד מבקש אישור בסשנים אינטראקטיביים לפני שימוש בשרתים בהיקף פרויקט מתוך קובצי .mcp.json. כדי לאפס את בחירות האישור, הריצו claude mcp reset-project-choices.

בהרצות claude -p, בסשנים של Agent SDK ובסשנים בענן, קלוד קוד אינו יכול להציג בקשה זו, ולכן הוא טוען שרתים בהיקף פרויקט ללא שאלה. קלוד קוד מדלג על הבקשה גם בסשן שמופעל במצב bypassPermissions כאשר ההגדרה skipDangerousModePermissionPrompt מוגדרת בהגדרות המשתמש או בהגדרות מנוהלות. כדי למנוע טעינת שרת בכל זאת:

  • הוסיפו אותו להגדרה disabledMcpjsonServers, החוסמת אותו בכל מצב הרשאה.
  • החריגו הגדרות פרויקט לחלוטין בעזרת הדגל --setting-sources או אפשרות settingSources ב-SDK.
  • הפעילו את הסשן עם --strict-mcp-config. במצב זה קלוד קוד משתמש רק בשרתי ה-MCP שהועברו ב---mcp-config. דילוג על בקשת האישור עבור שרתי פרויקט שקלוד קוד אינו טוען דורש גרסה v2.1.246 ומעלה. לפני גרסה זו, סשן strict עדיין המתין לאישור עבורם, מה שהשאיר סשנים ברקע ממתינים בעת ההפעלה.

#היקף משתמש

שרתים בהיקף משתמש נשמרים ב-~/.claude.json וזמינים בכל הפרויקטים במחשב שלכם, תוך שהם נשארים פרטיים לחשבון המשתמש שלכם. היקף זה מתאים לשרתי שירות אישיים, כלי פיתוח או שירותים שאתם משתמשים בהם לעיתים קרובות בין פרויקטים שונים.

# Add a user server
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

#היררכיית היקפים וקדימות

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

  1. היקף מקומי (local)
  2. היקף פרויקט (project)
  3. היקף משתמש (user)
  4. שרתים המסופקים על ידי תוספים
  5. מחברי claude.ai

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

שרת שהארגון מספק באמצעות ההגדרה המנוהלת managedMcpServers מקבל קדימות מעל כל אלה, כך שבמקרה של כפילות קלוד קוד יחבר את הגדרת הארגון (נדרשת גרסה v2.1.259 ומעלה).

אם פותחים סשן מקומי בלשונית Code באפליקציית שולחן העבודה עם אותו שם של שרת stdio ברמה העליונה של ~/.claude.json (היקף משתמש) וב-.mcp.json, הלשונית תשתמש בהגדרה מ-~/.claude.json.

#הרחבת משתני סביבה ב-.mcp.json

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

#תחביר נתמך

  • ${VAR}: מורחב לערך משתנה הסביבה VAR.
  • ${VAR:-default}: מורחב ל-VAR אם הוא מוגדר, ואחרת משתמש ב-default.

#מיקומי הרחבה

משתני סביבה יכולים להתרחב ב:

  • command: נתיב קובץ ההפעלה של השרת.
  • args: ארגומנטים של שורת הפקודה.
  • env: משתני סביבה המועברים לתהליך השרת.
  • url: עבור סוגי שרתי HTTP.
  • headers: עבור אימות שרתי HTTP.

#דוגמה עם הרחבת משתנים

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

#משתנים שלא הוגדרו ללא ברירת מחדל

אם משתנה סביבה שמצוין אינו מוגדר ואין לו ערך ברירת מחדל, התצורה עדיין נטענת: קלוד קוד מדווח על אזהרת משתנה חסר עבור אותו שרת בפלט claude mcp list וב-/mcp, ומשתמש בטקסט ${VAR} כפי שהוא ללא הרחבה. הגדירו את המשתנה או הוסיפו ערך ברירת מחדל :-default כדי שהשרת יופעל עם הערך המיועד. ב-url וב-headers של שרת מרוחק, משתני פרטי אימות מסוימים נקראים כריקים במקום זאת, ללא אזהרה.

#משתני פרטי אימות הנקראים כריקים

ב-url וב-headers של שרת מרוחק, קלוד קוד קורא משתני פרטי אימות מסביבתכם כריקים במקום להרחיב אותם. הדבר מונע מקובץ .mcp.json של פרויקט או מתוסף לשלוח את פרטי האימות של קלוד קוד או של ספק הענן שלכם לשרת שהם מציינים. אם תכתבו Bearer ${ANTHROPIC_AUTH_TOKEN}, השרת יקבל Bearer ללא פרטי אימות וידחה את הבקשה, בדרך כלל עם שגיאת 401. קלוד קוד מדווח על כך כחיבור שנכשל.

השמות המכוסים כוללים:

  • פרטי האימות של קלוד קוד עצמו, כגון ANTHROPIC_API_KEY ו-ANTHROPIC_AUTH_TOKEN.
  • פרטי האימות של ספק הענן שלכם, כגון AWS_BEARER_TOKEN_BEDROCK.
  • פרטי אימות נוספים שסביבתכם נושאת, כגון HTTPS_PROXY ו-NPM_TOKEN.

שם מכוסה נקרא כריק בין אם הגדרתם את המשתנה ובין אם לאו, וברירת מחדל :-default עליו מתעלמת. כתובת בסיס של ספק, כגון ANTHROPIC_BASE_URL, עדיין מתרחבת, כך ש-"url": "${ANTHROPIC_BASE_URL}/mcp" פועל, אלא אם ערך ה-URL עצמו מטמיע פרטי אימות כגון שם משתמש וסיסמה.

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

כאשר url או headers של שרת מרוחק מפנים למשתנה מכוסה שהגדרתם, קלוד קוד מציין זאת בשורת יומן ניפוי שגיאות (debug log). לקריאת השורה, הריצו claude --debug-file /tmp/claude-debug.log וחפשו בקובץ never expanded toward a remote server.

#כיצד הפניות מופיעות ב-/mcp ובפלט ה-CLI

עבור שרת בהיקף מקומי, פרויקט או משתמש, המקומות הבאים מציגים הפניה ל-${VAR} לפי שמה ולא לפי הערך המפוענח שלה:

  • ה-URL או שורת הפקודה בתצוגת הפרטים של השרת ב-/mcp (החל מגרסה v2.1.268 ומעלה).
  • פלט הפקודות claude mcp list ו-claude mcp get.

עבור שרת שהארגון מספק דרך הגדרת managedMcpServers, מקומות אלו מציגים את מארח ה-URL בלבד.

#דוגמאות מעשיות

#דוגמה: חיבור ל-GitHub לסקירת קוד

שרת ה-MCP המרוחק של GitHub מבצע אימות בעזרת טוקן גישה אישי (Personal Access Token) של GitHub המועבר בכותרת. כדי לקבל טוקן, פתחו את הגדרות הטוקנים ב-GitHub, צרו טוקן fine-grained חדש עם גישה למאגרים שתרצו שקלוד יעבוד מולם, ולאחר מכן הוסיפו את השרת:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

החליפו את YOUR_GITHUB_PAT בטוקן הגישה האישי שלכם. הפקודה claude mcp add שומרת את התצורה ללא אימות תקינות של הפרטים, כך שערך מציין מקום יתקבל כאן אך השרת ייכשל בחיבור מאוחר יותר. כדי לוודא את החיבור, הריצו /mcp ובדקו שהשרת מציג connected. שרת עם פרטי גישה שגויים מציג failed, ופירוט הכשל כולל את קוד ה-HTTP שהשרת החזיר, כגון 401.

לאחר מכן עבדו מול GitHub:

Review PR #456 and suggest improvements
Create a new issue for the bug we just found
Show me all open PRs assigned to me

#דוגמה: תשאול מסד נתוני PostgreSQL

החבילה @bytebase/dbhub (DBHub) היא שרת MCP שמחבר את קלוד למסד נתונים יחסי דרך מחרוזת החיבור שאתם מעבירים ב---dsn. השתמשו במשתמש מסד נתונים לקריאה בלבד (read-only) במחרוזת החיבור כדי ששאילתות שקלוד מריץ לא יוכלו לשנות נתונים:

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:[email protected]:5432/analytics"

כדי לאמת שהשרת מופעל, הריצו /mcp ובדקו ש-db מציג connected.

לאחר מכן שאלו שאלות בשפה טבעית:

What's our total revenue this month?
Show me the schema for the orders table
Find customers who haven't made a purchase in 90 days

#אימות מול שרתי MCP מרוחקים

שרתי MCP רבים בענן דורשים אימות. קלוד קוד תומך ב-OAuth 2.0 לחיבורים מאובטחים.

קלוד קוד מסמן שרת מרוחק כדורש אימות כאשר השרת מחזיר 401 Unauthorized או 403 Forbidden. מה שקלוד קוד מציג תלוי בשרת:

  • עבור שרת שטרם התחברתם אליו, כל אחד מקודי הסטטוס מסמן אותו ב-/mcp כדי שתוכלו להשלים את תהליך ה-OAuth.
  • עבור מחבר claude.ai, קוד 401 שנגרם עקב דחיית טוקן הסשן על ידי claude.ai אינו מסמן את המחבר, מכיוון שהרשאה מחדש של המחבר לא תפתור בעיה בהתחברות הראשית שלכם. קלוד קוד מציג מצב של דחיית טוקן סשן.
  • עבור שרת שכותרת ה-Authorization שלו הוגדרה ידנית, ב-headers או דרך headersHelper, קוד 401 או 403 בעת החיבור אינו מסמן את השרת, מכיוון שפרטי האימות לתיקון הם אלה שהגדרתם. קלוד קוד מדווח על החיבור כנכשל במקום זאת. אם הגדרתם כותרת זו מהפניה ל-${VAR}, בדקו האם המשתנה נמנה על אלה שקלוד קוד קורא כריקים.
  • עבור מחבר בסשן ענן, קלוד קוד אינו מריץ תהליך התחברות, מכיוון שהפרוקסי של הסשן מבצע אימות מול המחבר בעזרת ההרשאה שנתתם ב-claude.ai. אם מחבר כזה דורש אימות מחדש, חברו אותו מחדש בכתובת claude.ai/customize/connectors ולא מתוך הסשן.

כאשר בקשה לשרת OAuth שכבר התחברתם אליו מחזירה 401 Unauthorized, קלוד קוד מרענן את הטוקן השמור, מתחבר מחדש ומנסה את הבקשה שוב פעם אחת. הוא מסמן את השרת ב-/mcp רק אם גם הניסיון החוזר נכשל. לפני גרסה v2.1.206, כשל ברענון טוקן מסיבה זמנית, כגון שגיאת רשת, סימן שרת OAuth כדורש אימות למשך שארית הסשן אף שטוקן הרענון שלו עדיין היה תקף.

כאשר השרת דוחה את טוקן הרענון השמור, קלוד קוד מציג מיד הודעה המפנה ל-/mcp. פתחו את /mcp ובחרו Re-authenticate על השרת כדי להתחבר מחדש לפני שקריאת הכלי הבאה תיכשל.

שרת מותאם אישית שמחזיר כותרת WWW-Authenticate המצביעה על שרת ההרשאות שלו מקבל את אותו גילוי אוטומטי כמו כל שרת מרוחק אחר.

קלוד קוד מציג גם הודעה בעת ההפעלה כאשר שרת מוגדר אחד או יותר דורש אימות, כך שאינכם צריכים לפתוח את /mcp כדי לגלות אילו שרתים זקוקים להתחברות. ההודעה דורשת קלוד קוד מגרסה v2.1.193 ומעלה. היא סופרת רק שרתים שניתן להתחבר אליהם מתוך קלוד קוד. לפני גרסה v2.1.218, היא ספרה גם מחברי claude.ai שלא חוברו ב-claude.ai, אותם ניתן לחבר רק מהגדרות claude.ai.

ההודעה מודיעה על כל שרת פעם אחת ומשמיטה אותו מהספירה בהפעלות מאוחרות יותר עד שהשרת יתחבר ויזדקק להתחברות שוב. לוח /mcp עדיין מפרט כל שרת הדורש התחברות.

במצב לא אינטראקטיבי אין לוח /mcp, ולכן קלוד קוד אינו יכול להריץ את תהליך ה-OAuth עבורכם. החל מגרסה v2.1.196, כאשר שרת מוגדר דורש אימות במהלך ריצת claude -p או Agent SDK עם חיפוש כלים מופעל (ברירת המחדל), קלוד קוד מדווח לקלוד שכלי השרת אינם זמינים עד שתאשרו אותו. קלוד יכול אז לציין את שם השרת הדורש התחברות במקום להגיב כאילו השרת אינו מוגדר. השלימו את ההתחברות מסשן אינטראקטיבי באמצעות /mcp או claude mcp login <name>.

אם הגדרתם את headers.Authorization עבור השרת והשרת דוחה כותרת זו, קלוד קוד מדווח על החיבור כנכשל במקום לסגת ל-OAuth. בדקו שהטוקן תקין עבור נקודת הקצה של ה-MCP, או הסירו את הכותרת כדי להשתמש בתהליך ה-OAuth.

  1. הוספת השרת שדורש אימות: אם כבר הוספתם את שרת sentry ב-quickstart, דלגו על שלב זה: הרצת claude mcp add שוב עם אותו שם שרת באותו היקף תיכשל עם הודעה MCP server sentry already exists in local config. אחרת, הריצו:

    claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

  2. שימוש בפקודת /mcp בתוך קלוד קוד: בתוך קלוד קוד, השתמשו בפקודה:

    /mcp

    לאחר מכן פעלו לפי השלבים בדפדפן כדי להתחבר.

טיפים לאימות:

  • טוקני אימות נשמרים בצורה מאובטחת ומתרעננים אוטומטית.
  • השתמשו באפשרות "Clear authentication" בתפריט /mcp כדי לבטל גישה.
  • אם הדפדפן אינו נפתח אוטומטית, העתיקו את ה-URL שסופק ופתחו אותו ידנית.
  • אם ההפניה החוזרת (redirect) בדפדפן נכשלת עם שגיאת חיבור לאחר האימות, הדביקו את כתובת ההפניה המלאה משורת הכתובות של הדפדפן לתוך שורת הבקשה שמופיעה בקלוד קוד.
  • אימות OAuth פועל מול שרתי HTTP.

#אימות משורת הפקודה

החל מגרסה v2.1.186, הפקודה claude mcp login <name> מריצה את תהליך ה-OAuth של שרת מוגדר ישירות מהמעטפת שלכם, כך שאינכם צריכים לפתוח את לוח /mcp בתוך סשן:

claude mcp login sentry

למחיקת פרטי אימות שמורים מאוחר יותר, הריצו claude mcp logout <name>.

החל מגרסה v2.1.191, הפקודה מזהה כאשר אין דפדפן מקומי זמין, כגון בסשן SSH או בלינוקס ללא שרת תצוגה גרפי, ומדפיסה את כתובת ההרשאה במקום לנסות לפתוח דפדפן. פתחו את הכתובת במחשב המקומי שלכם, והדביקו את כתובת ההפניה המלאה משורת הכתובות של הדפדפן בחזרה אל שורת הבקשה. הפקודה דורשת טרמינל אינטראקטיבי לשלב ההדבקה, לכן התחברו עם ssh -t. העבירו --no-browser כדי לאלץ הצגת כתובת גם אם מזוהה דפדפן מקומי:

claude mcp login sentry --no-browser

#שימוש בפורט callback קבוע ל-OAuth

שרתי MCP מסוימים דורשים רישום מראש של כתובת הפניה חוזרת (redirect URI) ספציפית. כברירת מחדל, קלוד קוד בוחר פורט אקראי פנוי עבור ה-callback של OAuth. השתמשו בדגל --callback-port כדי לקבע את הפורט כך שיתאים לכתובת רשומה מראש במבנה http://localhost:PORT/callback. אם התחברות בגרסה v2.1.229 נכשלת עקב אי-התאמה בכתובת ההפניה, ראו את הערת הגרסה תחת שימוש בפרטי אימות OAuth שהוגדרו מראש.

ניתן להשתמש ב---callback-port לבדו (עם רישום לקוח דינמי) או יחד עם --client-id (עם פרטי אימות שהוגדרו מראש):

# Fixed callback port with dynamic client registration
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

#שימוש בפרטי אימות OAuth שהוגדרו מראש

שרתי MCP מסוימים אינם תומכים בהגדרה אוטומטית של OAuth באמצעות Dynamic Client Registration. אם נתקלתם בשגיאה כגון "Incompatible auth server: does not support dynamic client registration", השרת דורש פרטי אימות שהוגדרו מראש. קלוד קוד תומך גם בשרתים המשתמשים ב-Client ID Metadata Document (CIMD) במקום Dynamic Client Registration, ומגלה אותם אוטומטית. אם הגילוי האוטומטי נכשל, רשמו אפליקציית OAuth דרך פורטל המפתחים של השרת תחילה, וספקו את פרטי האימות בעת הוספת השרת:

  1. רישום אפליקציית OAuth מול השרת: צרו אפליקציה דרך פורטל המפתחים של השרת ורשמו את ה-client ID ואת ה-client secret שלכם.

    שרתים רבים דורשים גם redirect URI. אם כן, בחרו פורט ורשמו redirect URI במבנה http://localhost:PORT/callback. השתמשו באותו פורט עם --callback-port בשלב הבא.

    בגרסה v2.1.229, קלוד קוד שלח http://127.0.0.1:PORT/callback במקום זאת, ושרתים שבדקו התאמה מדויקת ל-redirect URI הרשום דחו את ההתחברות עם שגיאת אי-התאמה. גרסה v2.1.231 החזירה את מבנה localhost. להתאוששות בגרסה v2.1.229, שדרגו את קלוד קוד, או הוסיפו זמנית את מבנה http://127.0.0.1:PORT/callback לכתובות ההפניה הרשומות בשרת.

  2. הוספת השרת עם פרטי האימות: בחרו באחת מהשיטות הבאות. הפורט המשמש עבור --callback-port יכול להיות כל פורט פנוי, ועליו להתאים ל-redirect URI שרשמתם בשלב הקודם:

    באמצעות claude mcp add: השתמשו ב---client-id כדי להעביר את ה-client ID של האפליקציה. הדגל --client-secret מבקש את הסוד בקלט מוסתר:

    claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

    באמצעות claude mcp add-json: כללו את האובייקט oauth בתצורת ה-JSON והעבירו את --client-secret כדגל נפרד:

    claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

    באמצעות claude mcp add-json (פורט callback בלבד): השתמשו ב---callback-port ללא client ID כדי לקבע את הפורט תוך שימוש ברישום לקוח דינמי:

    claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

    בסביבת CI או באמצעות משתנה סביבה: הגדירו את הסוד דרך משתנה סביבה כדי לדלג על הבקשה האינטראקטיבית:

    MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

  3. אימות בתוך קלוד קוד: הריצו /mcp בקלוד קוד ועקבו אחר תהליך ההתחברות בדפדפן.

דגשים:

  • ה-client secret נשמר בצורה מאובטחת ב-keychain של המערכת (ב-macOS) או בקובץ פרטי אימות, ולא בתצורה שלכם.
  • ניתן להגדיר את ה-client secret רק בעת הוספת השרת. כאשר אתם מתחברים עם claude mcp login או מתוך /mcp, קלוד קוד משתמש בסוד השמור ואינו מבקש סוד או קורא את MCP_CLIENT_SECRET.
  • כדי להוסיף או לשנות את הסוד מאוחר יותר, הסירו את השרת עם claude mcp remove <name>, ואז הוסיפו אותו שוב עם --client-secret ובאותו --scope.
  • אם השרת משתמש בלקוח OAuth ציבורי ללא סוד, השתמשו רק ב---client-id ללא --client-secret.
  • דגלים אלה חלים על תעבורת HTTP ו-SSE בלבד. אין להם השפעה על שרתי stdio.
  • השתמשו ב-claude mcp get <name> כדי לוודא שפרטי OAuth מוגדרים עבור שרת.

#דריסת גילוי מטא-דאטה של OAuth

הפנו את קלוד קוד לכתובת URL ספציפית של מטא-דאטה של שרת הרשאות OAuth כדי לעקוף את שרשרת הגילוי כברירת מחדל. הגדירו את authServerMetadataUrl כאשר נקודות הקצה הסטנדרטיות של שרת ה-MCP מחזירות שגיאה, או כאשר ברצונכם לנתב את הגילוי דרך פרוקסי פנימי. כברירת מחדל, קלוד קוד בודק תחילה מטא-דאטה של משאב מוגן לפי RFC 9728 בכתובת /.well-known/oauth-protected-resource, ולאחר מכן נסוג למטא-דאטה של שרת הרשאות לפי RFC 8414 בכתובת /.well-known/oauth-authorization-server.

הגדירו את authServerMetadataUrl בתוך האובייקט oauth בתצורת השרת ב-.mcp.json:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

ה-URL חייב להשתמש ב-https://. השדה scopes_supported של כתובת המטא-דאטה דורס את ההרשאות שהשרת המרוחק מפרסם.

#הגבלת הרשאות OAuth (scopes)

הגדירו את oauth.scopes כדי לקבע את ההרשאות שקלוד קוד מבקש במהלך תהליך האימות. זו הדרך הנתמכת להגביל שרת MCP לתת-קבוצה המאושרת על ידי צוות האבטחה כאשר שרת ההרשאות מפרסם יותר הרשאות ממה שברצונכם להעניק. הערך הוא מחרוזת יחידה מופרדת ברווחים, בהתאם למבנה הפרמטר scope ב-RFC 6749 סעיף 3.3:

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

השדה oauth.scopes מקבל קדימות הן על פני authServerMetadataUrl והן על פני ההרשאות שהשרת מגלה ב-/.well-known. השאירו אותו לא מוגדר כדי לאפשר לשרת ה-MCP לקבוע את קבוצת ההרשאות המבוקשת.

החל מגרסה v2.1.196, כאשר oauth.scopes אינו מוגדר, קלוד קוד מבקש את ההרשאה שסופקה על ידי כותרת WWW-Authenticate של השרת או על ידי המטא-דאטה של המשאב המוגן שלו, ואינו שולח פרמטר scope כאשר אף אחד מהם אינו מספק הרשאה. הוא אינו מבקש עוד את כל קטלוג ה-scopes_supported ממטא-דאטה של שרת הרשאות שנתגלה אוטומטית. בקשת כל הקטלוג גרמה לספקי זהות המפרסמים הרשאות ניהוליות או תבניות לדחות את בקשת ההרשאה עם שגיאת invalid_scope. מטא-דאטה שנמשך מ-authServerMetadataUrl שהוגדר עדיין מספק את scopes_supported שלו כהרשאות המבוקשות.

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

אם השרת מחזיר בהמשך 403 insufficient_scope עבור קריאת כלי, הקריאה נכשלת עם הודעת needs additional permissions המציינת את ההרשאה שהשרת מבקש. השרת מוצג כדורש אימות ב-/mcp.

אם הרשאה זו אינה נמצאת ברשימת oauth.scopes המקובעת שלכם, הוסיפו אותה, לאחר מכן הריצו /mcp ואמתו את השרת שוב. קלוד קוד מבקש את ההרשאות המקובעות ולא את ההרשאה שהשרת ציין, כך שאם תאמתו שוב מבלי להוסיף אותה, הטוקן שתקבלו עדיין יחסר אותה.

#שימוש בכותרות דינמיות לאימות מותאם אישית

אם שרת ה-MCP שלכם משתמש בסכמת אימות שאינה OAuth, כגון Kerberos, טוקנים קצרי מועד או SSO פנימי, השתמשו ב-headersHelper כדי לייצר כותרות בקשה בזמן החיבור. קלוד קוד מריץ את הפקודה וממזג את הפלט שלה לתוך כותרות החיבור:

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

הפקודה יכולה להיות גם פקודת שורה:

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

דרישות:

  • על הפקודה לכתוב ל-stdout אובייקט JSON של זוגות מחרוזות מפתח-ערך.
  • קלוד קוד מריץ את הפקודה במעטפת ומוותר עליה לאחר 10 שניות.
  • קלוד קוד בוחר את ספריית העבודה של הפקודה לפי המקום שבו הגדרתם את השרת, לכן ספקו את הסקריפט כנתיב מוחלט או מקמו אותו ב-PATH.
  • כותרות דינמיות דורסות כל כותרת סטטית ב-headers בעלת אותו שם.

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

אם קריאת כלי מחזירה 401 Unauthorized או 403 Forbidden, קלוד קוד מריץ אוטומטית את ה-helper מחדש תחת אותו כלל, מתחבר מחדש עם הכותרות העדכניות, ומנסה את הקריאה שוב פעם אחת. קלוד קוד מסמן את השרת כדורש אימות ב-/mcp רק אם גם ניסיון חוזר זה נכשל.

כאשר פלט ה-helper כולל כותרת Authorization, קלוד קוד משתמש בפרטי אימות אלה כאימות של השרת ואינו נסוג ל-OAuth עבור השרת.

אם השרת דוחה את פרטי האימות של ה-helper בעת החיבור, קלוד קוד מדווח על החיבור כנכשל במקום לסמן את השרת כדורש אימות. תקנו את פרטי האימות שה-helper מחזיר, ואז התחברו מחדש מתוך /mcp כדי להריץ את ה-helper שוב.

קלוד קוד מגדיר משתני סביבה אלה בעת הרצת ה-helper:

משתנהערך
CLAUDE_CODE_MCP_SERVER_NAMEשם שרת ה-MCP
CLAUDE_CODE_MCP_SERVER_URLכתובת ה-URL של שרת ה-MCP
CLAUDE_PLUGIN_ROOTספריית השורש של התוסף. מוגדר רק כאשר תוסף מספק את השרת

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

פקודת headersHelper המסופקת על ידי תוסף אינה יכולה להפנות לערכי ${user_config.*} של התוסף, מכיוון שהפקודה רצה דרך מעטפת. קלוד קוד מדווח על השרת כשגוי בתצורה עם שגיאה ואינו מחליף את הערך. שימו ${user_config.KEY} בשדה headers של השרת במקום זאת, שאינו מפוענח במעטפת, או תנו לסקריפט ה-helper לקרוא את הערך מקובץ תצורה. לפני גרסה v2.1.207, headersHelper החליף ערכי ${user_config.*}.

#היכן ה-helper רץ

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

היכן הגדרתם את השרתספריית עבודה
תוסף (plugin)ספריית השורש של התוסף. דורש קלוד קוד מגרסה v2.1.195 ומעלה
קובץ .mcp.json של פרויקט או שרת בהיקף מקומיספריית הפרויקט שבה השרת מוצהר
קובץ סוכן בפרויקט שלכם, שרת מאפשרות mcpServers של ה-SDK או ממתודת setMcpServers(), או --mcp-configספריית העבודה הראשית של הסשן
היקף משתמש, תצורת MCP מנוהלת, מחבר claude.ai, או קובץ סוכן מחוץ לפרויקט, כולל מתיקיית --add-dirספריית התצורה שלכם, ~/.claude אלא אם הגדרתם את CLAUDE_CONFIG_DIR

לפני גרסה v2.1.238, קלוד קוד הריץ את ה-helpers של שרתים בהיקף משתמש, שרתים מנוהלים ומחברי claude.ai, וכן של קובצי סוכן מחוץ לפרויקט, מתוך הספרייה שבה הפעלתם אותו.

#אילו משתנים ה-helper יכול לקרוא

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

  • מוסרים: שרת ב-.mcp.json של פרויקט או בתוסף, ושרת inline בקובץ סוכן מהפרויקט שלכם או מספריית --add-dir.
  • אינם מוסרים: שרת בהיקף משתמש או בהיקף מקומי, ב-MCP מנוהל, ממחבר claude.ai, או שסופק על ידי ה-SDK או --mcp-config, ושרת inline בקובץ סוכן מ-~/.claude/agents/, מהגדרות מנוהלות או שהועבר עם --agents.

מלבד משתני GIT_CONFIG_KEY_<n> של Git, קלוד קוד מסיר מסביבתכם כל משתנה ששמו נראה כמו פרטי אימות, כגון שם המכיל TOKEN, SECRET, PASSWORD, KEY או AUTH בכל שילוב אותיות, כך ש-ANTHROPIC_API_KEY ו-MY_REGISTRY_TOKEN מוסרים שניהם. קלוד קוד מסיר גם רשימה קבועה של משתני פרטי אימות ששמותיהם אינם תואמים לדפוס זה, כגון ANTHROPIC_CUSTOM_HEADERS.

כאשר כלל זה חל על ה-helper שלכם, דאגו שהסקריפט יקרא את פרטי האימות שלו מקובץ או ממאגר אישורים. אם ה-url של השרת נושא את הערך החי של אחד ממשתנים אלה, כגון MY_REGISTRY_TOKEN, הערך של CLAUDE_CODE_MCP_SERVER_URL שה-helper מקבל יוחלף בחלק זה ב-REDACTED.

#מתן אמון בתיקייה לפני הרצת headersHelper

קלוד קוד מריץ headersHelper כפקודת מעטפת שרירותית. עבור שרת בקובץ .mcp.json של פרויקט או בהיקף מקומי, הוא מריץ את ה-helper רק לאחר שאישרתם את תיבת הדו-שיח של אמון עבור ספריית הפרויקט שבה השרת מוצהר. לפני גרסה v2.1.238, סשן claude -p או SDK הריץ helpers אלה מבלי לבדוק אמון, וסשן אינטראקטיבי הריץ אותם ברגע שאישרתם אמון בתיקיית אב.

  • אמון שאינו נחשב: אמון בתיקיית אב, והאמון האוטומטי שסשן claude -p או SDK מקבל עבור הוקים בקובצי הגדרות.
  • עד שתאשרו אמון בתיקייה: קלוד קוד מחבר את השרת באמצעות הכותרות הסטטיות בלבד. בסשן claude -p או SDK הוא מדפיס גם שורת headersHelper not run אחת לכל שרת ל-stderr, ומסביר כיצד להעניק את האמון.
  • אמון ללא תיבת דו-שיח: הגדירו את projects["<path>"].hasTrustDialogAccepted ל-true ב-~/.claude.json. הערך <path> הוא הספרייה שעליה קלוד קוד מבסס את האמון.

קלוד קוד מחיל את אותו כלל על שרת המוצהר inline בקובץ סוכן, ובודק מהיכן הגיע קובץ הסוכן: הפרויקט שלכם, עבור קובץ בספריית .claude/agents/ שלו, או ספריית --add-dir. עד שתאשרו אמון באותו פרויקט או ספרייה בעצמם, קלוד קוד אינו טוען את השרת כלל, ולכן ה-helper שלו אינו רץ לעולם.

#הוספת שרתי MCP מתצורת JSON

אם יש לכם תצורת JSON של שרת MCP, תוכלו להוסיף אותה ישירות:

  1. הוספת שרת MCP מ-JSON:

#Basic syntax

claude mcp add-json ''

#Example: Adding an HTTP server with JSON configuration

claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

#Example: Adding a stdio server with JSON configuration

claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

#Example: Adding an HTTP server with pre-configured OAuth credentials

claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret


2. בדיקה שהשרת נוסף:

```bash
claude mcp get weather-api

טיפים:

  • ודאו שה-JSON מנוטרל (escaped) כראוי במעטפת שלכם.
  • ה-JSON חייב להתאים לסכמת התצורה של שרתי MCP.
  • ניתן להשתמש ב---scope user כדי להוסיף את השרת לתצורת המשתמש שלכם במקום לתצורה הספציפית לפרויקט.

#ייבוא שרתי MCP מ-Claude Desktop

אם כבר הגדרתם שרתי MCP ב-Claude Desktop, תוכלו לייבא אותם:

  1. ייבוא שרתים מ-Claude Desktop:

#Basic syntax

claude mcp add-from-claude-desktop


2. בחירת השרתים לייבוא:
לאחר הרצת הפקודה, תראו תיבת דו-שיח אינטראקטיבית המאפשרת לבחור אילו שרתים לייבא.

3. בדיקה שהשרתים יובאו:

```bash
claude mcp list

שמות שרתים שנוספו דרך פקודות claude mcp יכולים להכיל רק אותיות אנגליות, ספרות, מקפים וקווים תחתונים. Claude Desktop אינו מחיל מגבלה זו, ולכן שרת של Claude Desktop ששמו מכיל כל תו אחר, כגון רווח, אינו ניתן לייבוא. תהליך הייבוא מדווח על כל שם שהוא דוחה ועדיין מייבא את שאר השרתים שבחרתם. לפני גרסה v2.1.205, השם הלא תקין הראשון עצר את הייבוא ואף שרת מהנבחרים לא נוסף.

טיפים:

  • תכונה זו פועלת ב-macOS וב-Windows Subsystem for Linux (WSL) בלבד.
  • היא קוראת את קובץ התצורה של Claude Desktop מהמיקום הסטנדרטי שלו בפלטפורמות אלו.
  • השתמשו בדגל --scope user כדי להוסיף שרתים לתצורת המשתמש שלכם.
  • שרתים מיובאים שומרים על שמם מ-Claude Desktop כאשר השם מכיל רק אותיות, ספרות, מקפים וקווים תחתונים. קלוד קוד מדווח על שרת ששמו מכיל כל תו אחר ומדלג עליו.
  • אם שרתים בעלי אותו שם כבר קיימים, הם מקבלים סיומת מספרית (למשל server_1).

#שימוש בשרתי MCP מ-claude.ai

אם התחברתם לקלוד קוד באמצעות חשבון claude.ai, שרתי MCP שהוספתם ב-claude.ai, המכונים מחברים (connectors), זמינים אוטומטית בקלוד קוד:

  1. הגדרת שרתי MCP ב-claude.ai: הוסיפו שרתים בכתובת claude.ai/customize/connectors. בתוכניות Team ו-Enterprise, רק מנהלים יכולים להוסיף שרתים.

  2. אימות שרת ה-MCP: השלימו את שלבי האימות הנדרשים ב-claude.ai.

  3. הצגה וניהול שרתים בקלוד קוד: בתוך קלוד קוד, השתמשו בפקודה:

    /mcp

    שרתים מ-claude.ai מופיעים ברשימה עם סימונים המראים שהם מגיעים מ-claude.ai.

קלוד קוד מסמן מחבר כ-managed ב-/mcp ובמנהל התוספים /plugin כאשר הארגון שלכם מנהל את האימות שלו ב-claude.ai. סטטוס מנוהל אינו משנה את האופן שבו קלוד קוד מתחבר למחבר או מחיל את בקרות הכלים של הארגון.

מחברים שמעולם לא נכנסתם אליהם מקופלים מאחורי שורת Show unused connectors בסוף חלק ה-claude.ai, כך שרשימה שסופקה על ידי הארגון אינה ממלאת את הלוח. בחרו בשורה זו כדי להרחיב אותם. מחבר שנכנסתם אליו בעבר נשאר גלוי גם כאשר הוא זקוק כעת לאימות מחדש.

מחברים מ-claude.ai נמשכים רק כאשר שיטת האימות הפעילה שלכם היא התחברות מנוי claude.ai. הם אינם נטענים, גם אם הרצתם בעבר /login, במקרים הבאים:

  • כאשר ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN או apiKeyHelper פעילים.
  • כאשר ספק צד שלישי כגון Amazon Bedrock או Google Cloud Agent Platform פעיל.
  • כאשר ANTHROPIC_PROFILE, משתני פדרציה, או פרופיל Anthropic פעיל מספקים את פרטי האימות.
  • כאשר CLAUDE_CODE_OAUTH_TOKEN מחזיק טוקן מ-claude setup-token, היכול לבצע בקשות מודל בלבד.

אם /mcp אינו מציג מחבר שהוספתם, הריצו /status כדי לאשר איזו שיטת אימות פעילה. בטלו את משתנה הסביבה, הסירו את הגדרת apiKeyHelper, או כבו את הפרופיל, ואז הריצו /login כדי לבחור בחשבון ה-claude.ai שלכם.

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

אם /mcp מציג מחבר במצב connected · session token rejected, או שתצוגת הפרטים שלו מציגה claude.ai rejected the session token, פירוש הדבר ש-claude.ai דחה את הטוקן מהתחברות הקלוד קוד שלכם, בדרך כלל בגלל שתוקף ההתחברות פג ולא ניתן היה לרעננו. אישור המחבר מחדש אינו מנקה מצב זה, מכיוון שההרשאה של המחבר עצמו ב-claude.ai אינה מה שנדחה. כדי לנקות מצב זה:

  1. הריצו /login כדי להתחבר מחדש.
  2. חברו מחדש את המחבר מתוך /mcp.

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

שרת שהוספתם בקלוד קוד מקבל קדימות על פני מחבר claude.ai המצביע לאותו URL. כאשר זה קורה, /mcp מציג את המחבר כמוסתר ומראה כיצד להסיר את הכפילות אם אתם מעדיפים להשתמש במחבר.

מחברים מסוימים המתארחים ב-Anthropic, כגון Microsoft 365, Gmail ו-Google Calendar, אינם תומכים ב-OAuth מקומי מקלוד קוד מכיוון שספק הזהות מקבל רק את כתובת ההפניה ש-claude.ai רשם. כאשר שרת שהוספתם עם claude mcp add או ב-.mcp.json מצביע על אחד ממארחים אלה ואתם מנסים להתחבר אליו מ-/mcp או בעזרת claude mcp login, קלוד קוד מציג הודעה המציינת שהשרת מתארח ב-Anthropic ואינו תומך ב-OAuth מקומי (is Anthropic-hosted and doesn't support local OAuth), ומפנה אתכם לחבר את השירות בכתובת claude.ai/customize/connectors במקום זאת.

לאחר שתסירו את הרשומה שלכם עם claude mcp remove <name> ותחברו את השירות ב-claude.ai, המחבר יופיע בקלוד קוד באופן אוטומטי.

#איך מחברים מגיעים לקלוד קוד

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

היכן הסשן רץכיצד המחברים מגיעיםמה שולט בהם
סשנים בטרמינל, VS Code, JetBrains ו-Agent SDKקלוד קוד מושך אותם מ-claude.aiההגדרות בחלק זה ותצורת MCP מנוהלת
סשנים בענן (Cloud sessions)מארח הענן מעביר אותם פנימההגדרות ארגון claude.ai שלכם, בתוספת הגדרות רשימת היתר ורשימת דחייה שמגיעות לסשן וכל managed-mcp.json במארח שמריץ אותו
סשנים מקומיים ו-SSH באפליקציית שולחן העבודהאפליקציית שולחן העבודה מעבירה אותם בתוך התהליךרשומות blocked בבקרות כלי המחברים של הארגון שלכם

ההגדרות disableClaudeAiConnectors, ENABLE_CLAUDEAI_MCP_SERVERS ו-allowAllClaudeAiMcps פועלות רק על השורה הראשונה, כלומר על המחברים שקלוד קוד מושך בעצמו. שתי השורות האחרות נבדלות ממנה בדרכים הבאות:

  • סשנים בענן: רשומות allowedMcpServers ו-deniedMcpServers שמגיעות לסשן, למשל דרך הגדרות מנוהלות שרת, מסננות גם את המחברים שמועברים. הפרוקסי של הסשן משכתב את ה-URL של כל מחבר, כך שתבנית serverUrl שנכתבה עבור ה-URL המקורי של המחבר אינה תואמת לו. כדי לאפשר מחברים מועברים לצד רשימת היתר של כתובות URL בסביבה באירוח עצמי (self-hosted), הוסיפו את רשומות ה-serverUrl הנדרשות. קלוד קוד משמיט את המחברים המועברים כאשר קיים managed-mcp.json במארח המריץ את הסשן, בין אם הגדרתם allowAllClaudeAiMcps ובין אם לאו.
  • סשנים מקומיים ו-SSH באפליקציית שולחן העבודה: אפליקציית שולחן העבודה רושמת את המחברים כשרתי type: "sdk" בתוך התהליך, ואף הגדרת MCP או קובץ managed-mcp.json אינם מגיעים אליהם. משתמש מונע כניסת מחבר לסשנים שלו על ידי ניתוקו בכתובת claude.ai/customize/connectors. ארגון חוסם כלים של מחבר או מכבה את קלוד קוד באפליקציית שולחן העבודה לחלוטין.

#בקרות ארגוניות על כלי מחברים

הארגון שלכם יכול לקבוע בקרות פר-כלי על מחברי claude.ai. קלוד קוד קורא הגדרות אלו בעת ההפעלה ואוכף אותן מקומית, למעט בסשנים מקומיים ו-SSH באפליקציית שולחן העבודה. שם, אפליקציית שולחן העבודה מונעת כלים במצב blocked לפני שהיא מעבירה מחבר, וההגדרה ask אינה מגיעה לקלוד קוד, ולכן הוא מחיל את כללי ההרשאות הרגילים של הסשן על כלים אלה במקום לבקש אישור בכל קריאה. בסשנים שבהם קלוד קוד מושך מחברים בעצמו, הריצו /mcp כדי לראות איזו הגדרה חלה על כל כלי במחבר:

  • כלי המוגדר כ-ask: קלוד קוד מבקש אישור בכל קריאה עם הסיבה Your organization requires approval for this tool. הבקשה מופיעה אפילו במצבי הרשאה acceptEdits, auto ו-bypassPermissions, ולעולם אינה מציעה אפשרות לזכור את הבחירה. כללי היתר (allow rules) התואמים לכלי אינם מדלגים על הבקשה. במצב dontAsk, שאינו שואל לעולם, קלוד קוד דוחה את הקריאה במקום זאת.
  • כלי המוגדר כ-blocked: קלוד קוד מסנן את הכלי לפני שקלוד רואה אותו, כך שהוא אינו מופיע לעולם ברשימת הכלים. אפליקציית שולחן העבודה וצ'אט claude.ai מחילים את אותה הגדרת blocked, כך שקלוד אינו יכול להשתמש בכלי גם שם, ואינכם יכולים למנוע כלי מסשנים באפליקציית שולחן העבודה תוך השארתו זמין בצ'אט. אפליקציית שולחן העבודה מדלגת על מחבר שכל כליו חסומים.

#השבתת מחברי claude.ai

קלוד קוד מחיל את disableClaudeAiConnectors רק על המחברים שהוא מושך בעצמו, ולא על מחברים שמארח ענן או אפליקציית שולחן העבודה מעבירים. כדי לכבות את המחברים שהוא מושך, קבעו את ההגדרה ל-true בכל היקף הגדרות:

{
  "disableClaudeAiConnectors": true
}

הגדרה זו פועלת לפי סמנטיקת מקור-כלשהו-true: ערך true בכל מקור הגדרות מקבל קדימות. קובץ .claude/settings.json של פרויקט שנשמר ב-git יכול לבטל את המחברים שקלוד קוד מושך בעצמו עבור אותו מאגר, אך false ברמת הפרויקט אינו יכול להפעיל מחדש מחברים ש-true ברמת המשתמש או המדיניות השבית. שרתים שהועברו מפורשות דרך --mcp-config אינם מושפעים.

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

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

כדי לחסום מחברי claude.ai בודדים במקום את כולם, הוסיפו אותם ל-deniedMcpServers לפי שם או לפי תבנית URL. לדוגמה, רשומת serverName של "claude.ai Slack" חוסמת את מחבר Slack. ניתן גם להריץ /mcp כדי להפעיל או לכבות כל מחבר שקלוד קוד מושך עבור הפרויקט הנוכחי בלבד.

#שימוש בקלוד קוד כשרת MCP

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

# Start Claude as a stdio MCP server
claude mcp serve

הפקודה אינה מדפיסה דבר כאשר היא מתחילה. שרת MCP מסוג stdio מתקשר דרך stdin ו-stdout, ולכן טרמינל דומם וחסום מעיד שהשרת פועל וממתין לחיבור לקוח.

ניתן להשתמש בכך ב-Claude Desktop על ידי הוספת תצורה זו לקובץ claude_desktop_config.json:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

[!WARNING] הגדרת נתיב קובץ ההפעלה: השדה command חייב להפנות לקובץ ההפעלה של קלוד קוד. אם הפקודה claude אינה נמצאת ב-PATH של המערכת שלכם, תצטרכו לציין את הנתיב המלא לקובץ ההפעלה.

למציאת הנתיב המלא:

which claude

לאחר מכן השתמשו בנתיב המלא בתצורה שלכם:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "/full/path/to/claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

ללא נתיב קובץ הפעלה נכון, תיתקלו בשגיאות כגון spawn claude ENOENT.

טיפים:

  • ב-Claude Desktop, נסו לבקש מקלוד לקרוא קבצים בספרייה, לבצע עריכות ועוד.
  • שרת MCP זה חושף את הכלים של קלוד קוד ללקוח ה-MCP שלכם בלבד, כך שהלקוח שלכם אחראי על יישום אישור משתמש עבור קריאות כלים בודדות.

#מגבלות פלט ואזהרות של MCP

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

  • סף אזהרת פלט: קלוד קוד מציג אזהרה כאשר פלט של כלי MCP כלשהו חורג מ-10,000 טוקנים.
  • מגבלה הניתנת להגדרה: ניתן להתאים את כמות הטוקנים המרבית המותרת לפלט MCP באמצעות משתנה הסביבה MAX_MCP_OUTPUT_TOKENS.
  • מגבלת ברירת מחדל: ברירת המחדל המרבית היא 25,000 טוקנים.
  • תחולה: משתנה הסביבה חל על כלים שאינם מצהירים על מגבלה משלהם. כלים המגדירים את anthropic/maxResultSizeChars משתמשים בערך זה במקום זאת עבור תוכן טקסט, ללא קשר לערך המוגדר ב-MAX_MCP_OUTPUT_TOKENS. כלים שמחזירים נתוני תמונה עדיין כפופים ל-MAX_MCP_OUTPUT_TOKENS.
  • מעבר למגבלה: כאשר תוצאה ללא תוכן תמונה חורגת מהמגבלה, קלוד קוד שומר אותה לקובץ ומחליף אותה בשיחה בהודעה המציינת את נתיב הקובץ, כך שקלוד קורא את הקובץ כאשר הוא זקוק לתוכן. הקובץ נשמר בספריית tool-results של הסשן תחת ~/.claude/projects/.

להגדלת המגבלה עבור כלים המייצרים פלט גדול:

export MAX_MCP_OUTPUT_TOKENS=50000
claude

#העלאת המגבלה עבור כלי ספציפי

אם אתם בונים שרת MCP, תוכלו לאפשר לכלים בודדים להחזיר תוצאות גדולות יותר מסף השמירה לדיסק המוגדר כברירת מחדל על ידי הגדרת _meta["anthropic/maxResultSizeChars"] ברשומת הכלי בתגובת tools/list. קלוד קוד מעלה את סף הכלי לערך שצוין, עד לתקרה קשיחה של 500,000 תווים.

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

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

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

[!WARNING] אם אתם נתקלים לעיתים קרובות באזהרות פלט עם שרתי MCP שאינם בשליטתכם, שקלו להגדיל את מגבלת MAX_MCP_OUTPUT_TOKENS. תוכלו גם לבקש ממחבר השרת להוסיף את הסימון anthropic/maxResultSizeChars או לחלק את התגובות לעמודים (pagination). לסימון אין השפעה על כלים שמחזירים תוכן תמונה; עבורם, הגדלת MAX_MCP_OUTPUT_TOKENS היא האפשרות היחידה.

#סכמות קלט של כלים עם קומבינטור ברמת השורש

שרתי MCP מסוימים מגדירים סכמת קלט של כלי כאיחוד של JSON Schema, עם anyOf, oneOf או allOf ברמה העליונה של הסכמה. ה-API של Claude אינו מקבל מילות מפתח אלו בשורש הסכמה. הוא מקבל קומבינטורים המקוננים בתוך properties, אותם קלוד קוד שולח ללא שינוי.

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

  • allOf: מאפיינים מכל ענף ממוזגים, ורשימת required של כל ענף עדיין חלה.
  • anyOf ו-oneOf: מאפיינים מכל ענף ממוזגים, ורשימת required של כל ענף מתוארת בתיאור הכלי במקום להיאכף על ידי הסכמה.

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

כאשר קלוד קוד אינו יכול לייצר סכמה שה-API מקבל, או בפריסה שאינה מקבלת את התצורה המרוחקת המאפשרת את השכתוב, הוא מדלג על אותו כלי יחיד, מתעד את הסיבה ביומן השרת, ומשאיר את שאר כלי השרת זמינים. גרסאות קודמות ל-v2.1.195 מדלגות על כל כלי שסכמת הקלט שלו מכילה anyOf, oneOf או allOf ברמת השורש.

#כלים עם סכמות קלט לא תקינות

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

  • שמות מאפיינים ברמה העליונה חייבים להיות באורך 1 עד 64 תווים ולהשתמש רק באותיות ASCII, ספרות, _, . ו--.
  • הסכמה חייבת להיות תקינה מול מטא-סכמה של JSON Schema draft 2020-12. קלוד קוד מחיל בדיקה זו על סכמות שאינן מצהירות על $schema ועל סכמות המצהירות על draft 2020-12. סכמה המצהירה על כל דיאלקט אחר מדלגת על בדיקה זו, אם כי בדיקת שמות המאפיינים עדיין חלה.

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

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

קלוד קוד מפעיל את ההחרגה דרך דגל פיצ'ר שהוא מושך מ-Anthropic. בפריסה שבה משיכת דגלים כבויה, או במכונה שדגליה לא הגיעו מעולם (כגון מכונה מנותקת רשת, air-gapped), קלוד קוד עדיין מריץ את הבדיקות ומתעד ביומן השרת איזה כלי היה נדחה, אך שולח את סכמת הכלי ל-API בכל זאת. ה-API דוחה בקשה הכוללת סכמה זו בשגיאת 400 המציינת את הכלי לפי מיקומו. לפני גרסה v2.1.216, אף פריסה לא הריצה בדיקות אלו.

הטיפול בקומבינטור ברמת השורש נפרד ושומר על התנהגותו גם כאשר משיכת דגלים כבויה או כאשר הדגלים לא הגיעו מעולם.

#דרישת אישור עבור כלי ספציפי

אם אתם בונים שרת MCP, תוכלו לסמן כלי כדורש אישור מפורש בכל קריאה על ידי הגדרת _meta["anthropic/requiresUserInteraction"] ל-true ברשומת הכלי בתגובת tools/list. הערך חייב להיות ה-boolean של JSON true; כל ערך אחר מתעלם.

קלוד קוד מציג את בקשת ההרשאה של הכלי בכל קריאה, אפילו במצבי הרשאה acceptEdits, auto ו-bypassPermissions, ואינו מציע אפשרות "don't ask again" עבורו. כללי היתר התואמים לכלי אינם מדלגים על הבקשה. במצב dontAsk, שלעולם אינו שואל, קלוד קוד דוחה את הקריאה במקום זאת.

הבקשה חייבת להגיע לאדם. במצב לא אינטראקטיבי עם --permission-prompt-tool, תוצאת allow מכלי הבקשה עבור כלי מסומן מומרת לדחייה עם ההודעה MCP tool requires user interaction; not supported via --permission-prompt-tool. קריאת החזרה canUseTool ב-Agent SDK מקבלת קריאות אלו ויכולה לאשר אותן, מכיוון שאפליקציית ה-SDK שלכם צפויה להציג אותן למשתמש.

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

{
  "name": "grant_access",
  "description": "Requests access to a protected resource",
  "_meta": {
    "anthropic/requiresUserInteraction": true
  }
}

הסימון anthropic/requiresUserInteraction דורש קלוד קוד מגרסה v2.1.199 ומעלה. גרסאות קודמות מתעלמות ממנו ומחילות את תהליך ההרשאות הרגיל.

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

קלוד קוד מונע אישור בלחיצה אחת באותו אופן עבור כל בקשת הרשאה שרק תיבת הדו-שיח בטרמינל יכולה לעבד במלואה, כגון בקשה הנושאת אזהרת בטיחות או אפשרות של היתר קבוע שהמשטח המרוחק אינו יכול להציג. אתם משיבים לבקשה זו בתיבת הדו-שיח בטרמינל ולא מתוך Remote Control (דורש גרסה v2.1.214 ומעלה).

#מענה לבקשות איסוף מידע (elicitation) של MCP

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

שרתים יכולים לבקש קלט בשתי דרכים:

  • מצב טופס (Form mode): קלוד קוד מציג תיבת דו-שיח עם שדות טופס שהוגדרו על ידי השרת (לדוגמה, בקשת שם משתמש וסיסמה). ממלאים את השדות ושולחים.
  • מצב URL (URL mode): קלוד קוד פותח כתובת URL בדפדפן לצורך אימות או אישור. משלימים את התהליך בדפדפן, ולאחר מכן מאשרים ב-CLI.

במצב URL, קלוד קוד מעביר את ה-URL כארגומנט שורת פקודה למטפל ה-URL של המערכת שלכם, ומגביל את אורכו של ארגומנט זה. כאשר ה-URL, לאחר ניטרול עבור שורת הפקודה, עובר את המגבלה, באפשרותכם רק לדחות את הבקשה. כל תו שדורש ניטרול, כגון % או &, נספר ארבע פעמים כנגד המגבלה: התו עצמו ועוד שלושה תווי ניטרול. כתובת URL ללא תווים אלה מגיעה למגבלה בכ-8,000 תווים. כתובת URL הבנויה ברובה מקידודי אחוזים, שבה כל תו שלישי הוא %, מגיעה למגבלה בכ-4,000 תווים בקירוב.

כדי להגיב אוטומטית לבקשות elicitation מבלי להציג תיבת דו-שיח, השתמשו בהוק Elicitation.

אם אתם בונים שרת MCP המשתמש ב-elicitation, ראו את מפרט ה-elicitation של MCP לפרטי הפרוטוקול ודוגמאות סכמה.

#שימוש במשאבי MCP

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

#הפניה למשאבי MCP

  1. הצגת רשימת משאבים זמינים: הקלידו @ בהודעה שלכם כדי לראות משאבים זמינים מכל שרתי ה-MCP המחוברים. משאבים מופיעים לצד קבצים בתפריט ההשלמה האוטומטית.

  2. הפניה למשאב ספציפי: השתמשו במבנה @server:protocol://resource/path כדי להפנות למשאב:

    Can you analyze @github:issue://123 and suggest a fix?
    Please review the API documentation at @docs:file://api/authentication

  3. הפניות למספר משאבים: ניתן להפנות למספר משאבים בהודעה יחידה:

    Compare @postgres:schema://users with @docs:file://database/user-model

טיפים:

  • משאבים נמשכים אוטומטית ונכללים כקבצים מצורפים בעת הפניה אליהם.
  • נתיבי משאבים ניתנים לחיפוש מקורב (fuzzy search) בהשלמה האוטומטית של אזכור @.
  • קלוד קוד מספק אוטומטית כלים לרשימת משאבי MCP ולקריאתם כאשר שרתים תומכים בהם.
  • משאבים יכולים להכיל כל סוג תוכן ששרת ה-MCP מספק (טקסט, JSON, נתונים מובנים וכדומה).

#הרחבת קנה מידה עם חיפוש כלים (tool search) של MCP

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

[!NOTE] חיפוש כלים אינו נתמך בפריסות Microsoft Foundry המתארחות ב-Azure, הדוחות תכונה זו בצד השרת: קלוד קוד מזהה את הדחייה וטוען את כלי ה-MCP מראש עבור פריסה זו במקום זאת. הדגל ENABLE_TOOL_SEARCH אינו יכול לעקוף זאת, מכיוון שהדחייה מגיעה מהפריסה עצמה.

#למחברי שרתי MCP

אם אתם בונים שרת MCP, שדה הוראות השרת (server instructions) הופך לשימושי יותר כאשר חיפוש כלים מופעל. הוראות השרת מסייעות לקלוד להבין מתי לחפש את הכלים שלכם, באופן דומה לפעולתן של מיומנויות (skills).

הוסיפו הוראות שרת ברורות ותיאוריות המסבירות:

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

קלוד קוד קוטם תיאורי כלים והוראות שרת החורגים מ-2KB כל אחד. שמרו עליהם תמציתיים כדי למנוע קיטום, ומקמו פרטים קריטיים קרוב להתחלה.

#הגדרת חיפוש כלים

חיפוש כלים מופעל כברירת מחדל: כלי MCP נדחים ומתגלים לפי דרישה. קלוד קוד משבית אותו כאשר ANTHROPIC_BASE_URL מצביע על מארח שאינו צד ראשון, מכיוון שרוב שרתי הפרוקסי אינם מעבירים בלוקי tool_reference. הגדירו את ENABLE_TOOL_SEARCH באופן מפורש כדי לעקוף נסיגה זו.

הגדרת CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS שומרת את חיפוש הכלים כבוי. לא ניתן לעקוף זאת על ידי הגדרת ENABLE_TOOL_SEARCH בעצמכם. הארגון שלכם יכול לשמור על חיפוש כלים מופעל דרך הגדרות מנוהלות, בקלוד קוד מגרסה v2.1.227 ומעלה.

חיפוש כלים דורש מודל התומך בבלוקי tool_reference: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 ומודלים מאוחרים יותר.

ב-Agent Platform של Google Cloud, קלוד קוד מחליט לפי דור המודל:

  • Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 ומאוחרים יותר: חיפוש כלים מופעל כברירת מחדל, בדיוק כמו ב-API של Anthropic.
  • מודלים מוקדמים יותר ב-Agent Platform: קלוד קוד טוען את כל כלי ה-MCP מראש, מכיוון שמערכות ההגשה שלהם דוחות את כותרת הבטא הנדרשת. הגדרת ENABLE_TOOL_SEARCH=true אינה עוקפת זאת.

לפני גרסה v2.1.221, קלוד קוד השבית חיפוש כלים עבור כל המודלים ב-Agent Platform של Google Cloud אלא אם הגדרתם ENABLE_TOOL_SEARCH=true.

שליטה בהתנהגות חיפוש כלים באמצעות משתנה הסביבה ENABLE_TOOL_SEARCH:

ערךהתנהגות
(לא מוגדר)כל כלי ה-MCP נדחים ונטענים לפי דרישה. חוזר לטעינה מראש במודלים הקודמים לדור Claude 4.5 ב-Agent Platform של Google Cloud, כאשר ANTHROPIC_BASE_URL הוא מארח שאינו צד ראשון, או בפריסת Microsoft Foundry המתארחת ב-Azure
trueכל כלי ה-MCP נדחים, למעט בפריסת Microsoft Foundry המתארחת ב-Azure שבה דחיית צד השרת עדיין כופה טעינה מראש, ובמודלים הקודמים לדור Claude 4.5 ב-Agent Platform שבהם קלוד קוד ממשיך לטעון כלים מראש. קלוד קוד שולח את כותרת הבטא דרך פרוקסי, ובקשות ייכשלו בפרוקסי שאינו תומך בבלוקי tool_reference
autoמצב סף: קלוד קוד טוען מראש את הכלים שהיה דוחה כל עוד הגדרותיהם מסתכמות בפחות מ-10% מחלון ההקשר, ודוחה את כולם ברגע שההגדרות מגיעות ל-10%
auto:Nמצב סף עם אחוז מותאם אישית, כאשר N הוא בין 0 ל-100. לדוגמה, auto:5 עבור 5%
falseכל כלי ה-MCP נטענים מראש, ללא דחייה
# Use a custom 5% threshold
ENABLE_TOOL_SEARCH=auto:5 claude

# Disable tool search entirely
ENABLE_TOOL_SEARCH=false claude

ניתן להגדיר את הערך גם בשדה env בקובץ settings.json.

ניתן גם להשבית את הכלי ToolSearch באופן ספציפי:

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

#החרגת שרת מדחיית טעינה

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

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

השדה alwaysLoad זמין בכל סוגי השרתים. שרת MCP יכול גם לסמן כלים בודדים כטעונים תמיד על ידי הכללת "anthropic/alwaysLoad": true באובייקט _meta של הכלי, מה שמשיג את אותה תוצאה עבור אותו כלי בלבד.

הגדרת alwaysLoad: true גורמת להפעלת הסשן להמתין לכלי השרת, עד למגבלת פסק זמן חיבור סטנדרטית של 5 שניות, מכיוון שהם חייבים להיות נוכחים בעת בניית הפרומפט הראשון. שרת מרוחק עם רשומת cached תקפה מספק את כליו מהמטמון מבלי להתחבר, ולכן אינו מעכב את ההפעלה. שרתים אחרים מתחברים ברקע כברירת מחדל; הגדירו MCP_CONNECTION_NONBLOCKING=0 כדי לגרום להפעלה להמתין גם להם.

#שימוש ב-prompts של MCP כפקודות

שרתי MCP יכולים לחשוף פרומפטים שהופכים לזמינים כפקודות בתוך קלוד קוד.

#הפעלת פרומפטים של MCP

  1. גילוי פרומפטים זמינים: הקלידו / כדי לראות את הפקודות הזמינות עבורכם, כולל אלו שמקורן בשרתי MCP. קלוד קוד מציג כל פרומפט MCP במבנה /servername:promptname (MCP). הקלדת /mcp__servername__promptname מריצה אותו גם כן.

  2. הפעלת פרומפט ללא ארגומנטים:

    /mcp__github__list_prs

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

    /mcp__github__pr_review 456
    /mcp__jira__create_issue login-bug high

טיפים:

  • פרומפטים של MCP מתגלים באופן דינמי משרתים מחוברים.
  • ארגומנטים מפוענחים בהתאם לפרמטרים שהוגדרו בפרומפט.
  • תוצאות הפרומפט מוזרקות ישירות לתוך השיחה.
  • במבנה /mcp__servername__promptname, קלוד קוד מחליף כל תו בשם השרת שאינו אות אנגלית, ספרה, מקף או קו תחתון ב-_, ומשתמש בשם הפרומפט כפי שהשרת הצהיר עליו.

#תצורת MCP מנוהלת

עבור ארגונים הזקוקים לשליטה מרכזית על שרתי ה-MCP שמשתמשים יכולים להתחבר אליהם, ראו תצורת MCP מנוהלת (Managed MCP configuration). התצורה המנוהלת מכסה פריסת קבוצת שרתים קבועה בעזרת managed-mcp.json, אספקת שרתים לכלל המשתמשים באמצעות managedMcpServers, הגבלת שרתים בעזרת allowedMcpServers ו-deniedMcpServers, ומה המשתמשים רואים כאשר שרת נחסם.