למד איך לחבר את Claude Code לכלים שלך עם Model Context Protocol.
Claude Code יכול להתחבר למאות כלים ומקורות נתונים חיצוניים דרך Model Context Protocol (MCP), תקן קוד פתוח לאינטגרציות של כלי AI. שרתי MCP נותנים ל-Claude Code גישה לכלים, למסדי הנתונים ול-API שלך.
חבר שרת כשאתה מוצא את עצמך מעתיק נתונים לצ'אט מכלי אחר, כמו מערכת מעקב תקלות או לוח ניטור. אחרי החיבור, Claude יכול לקרוא ולפעול על המערכת הזאת ישירות במקום לעבוד ממה שהדבקת.
אם אתה מחבר את השרת הראשון שלך, התחל ב-מדריך המהיר ל-MCP למעבר צעד אחר צעד. הדף הזה הוא המדריך המלא.
ליישם תכונות ממערכות מעקב תקלות: "הוסף את התכונה שמתוארת בבעיה ENG-4521 ב-JIRA וצור PR ב-GitHub."
לנתח נתוני ניטור: "בדוק ב-Sentry וב-Statsig את השימוש בתכונה שמתוארת ב-ENG-4521."
לתשאל מסדי נתונים: "מצא כתובות אימייל של 10 משתמשים אקראיים שהשתמשו בתכונה ENG-4521, על סמך מסד הנתונים PostgreSQL שלנו."
לשלב עיצובים: "עדכן את תבנית האימייל הסטנדרטית שלנו לפי עיצובי Figma החדשים שפורסמו ב-Slack"
להפוך תהליכי עבודה לאוטומטיים: "צור טיוטות Gmail שמזמינות את 10 המשתמשים האלה למפגש משוב על התכונה החדשה."
להגיב לאירועים חיצוניים: שרת MCP יכול גם לפעול כ-ערוץ שדוחף הודעות לתוך הסשן, כך ש-Claude מגיב להודעות Telegram, לשיחות Discord או לאירועי webhook בזמן שאתה לא נמצא.
עיין במחברים שנבדקו ב-Anthropic Directory. מחברי Directory משתמשים באותה תשתית MCP כמו Claude Code, כך שאפשר להוסיף כל שרת מרוחק שמופיע שם עם claude mcp add.
[!WARNING]
ודא שאתה סומך על כל שרת לפני שאתה מחבר אותו. שרתים שמושכים תוכן חיצוני עלולים לחשוף אותך ל-סיכון של הזרקת פרומפט.
אפשר גם לבקש מ-Claude לבנות שלד של שרת עם התוסף הרשמי mcp-server-dev.
1. התקנת התוסף
בתוסף VS Code או באפליקציית שולחן העבודה, עקוב אחרי התקנת תוסף במקום השלב הזה. בטרמינל, הפעל את Claude Code באמצעות הרצת claude, ואז הזן את זה בשורת הפקודה שלו:
אם ההתקנה נכשלת, התאם את ההודעה ש-Claude Code מדווח:
Marketplace "claude-plugins-official" not found: הוסף את ה-marketplace עם /plugin marketplace add anthropics/claude-plugins-official, ואז נסה שוב את ההתקנה.
Plugin "<name>" not found in marketplace "claude-plugins-official": העותק המקומי של קטלוג ה-marketplace עלול להיות לא מעודכן. רענן אותו עם /plugin marketplace update claude-plugins-official, ואז נסה שוב את ההתקנה. אם הניסיון החוזר מדפיס את אותה הודעה, ראה התוסף לא נמצא ב-marketplace.
אם סיכום ההתקנה מדווח Run /reload-plugins to apply., Claude Code מריץ את הטעינה מחדש הזאת בשבילך. אם הטעינה מחדש מזהירה שההודעה הבאה שלך תקרא מחדש את השיחה, הרץ /reload-plugins --force.
2. הרצת מיומנות הבנייה
/mcp-server-dev:build-mcp-server
Claude שואל על מקרה השימוש שלך ובונה שלד של שרת HTTP מרוחק או שרת stdio מקומי.
שרתי 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 היא שגיאת הגדרה, כי Claude Code קורא רשומה בלי type כשרת stdio. Claude Code מדלג על השרת הזה ומדווח MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry.
רק יישום מארח SDK, כמו יישום Agent SDK או אפליקציית שולחן העבודה, יכול לרשום שרת "type": "sdk" בתוך התהליך. Claude Code מדלג על רשומת "type": "sdk" ב-.mcp.json, ב-~/.claude.json או בהגדרות ומדווח Skipped , MCP server "<name>" declares type "sdk", which only an SDK host application can register.
[!NOTE]
בהרצות --output-format stream-json, Claude Code גם מדווח על רשומת --mcp-config שדולגה בשדה mcp_server_errors של אירוע system/init, כך שסקריפטים יכולים לזהות שהשרת לא נטען.
תעבורת SSE (Server-Sent Events) הוצאה משימוש. השתמש בשרתי HTTP במקום, כשהם זמינים.
חלק מהשירותים עדיין חושפים רק נקודת קצה SSE. הוסף אותם עם אותה פקודה claude mcp add --transport http <name> <url> כמו שרת HTTP. Claude Code מנסה קודם את תעבורת HTTP ועובר ל-SSE כשהשרת לא מקבל אותה. המעבר האוטומטי דורש Claude Code בגרסה 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"
שרתי stdio רצים כתהליכים מקומיים במחשב שלך. הם מתאימים לכלים שצריכים גישה ישירה למערכת או לסקריפטים מותאמים.
Claude Code מגדיר את 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 במקום. Claude Code עונה ל-roots/list עם תיקיית ההפעלה של הסשן ועם כל תיקיית עבודה נוספת שהענקת עם --add-dir, /add-dir, או ההגדרה additionalDirectories. Claude Code שולח notifications/roots/list_changed כשהקבוצה הזאת משתנה.
המשתנה הזה מוגדר בסביבה של השרת, לא בסביבה של Claude Code עצמו, ולכן הפניה אליו דרך הרחבת ${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
[!NOTE]
בשרתי stdio, ה--- (מקף כפול) מפריד בין האפשרויות של Claude עצמו, כמו --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 בסביבה
בלי --, Claude Code ינסה לפרש את הדגלים של השרת, כמו --port למעלה, כאפשרויות שלו.
--env מקבל כמה זוגות KEY=value. אם שם השרת מגיע ישירות אחרי --env, ה-CLI קורא את השם כזוג נוסף ודוחה אותו, ולכן מקם לפחות אפשרות אחרת, כמו --transport stdio, בין --env לשם השרת.
כש-Claude Code מנתק שרת stdio, לדוגמה כשהסשן מסתיים, הוא מסמן לתהליך השרת וממתין בקצרה שהוא יצא לפני שהוא כופה עליו לעצור. אם השרת שומר מצב או מסיר קבצי נעילה בכיבוי, טפל באות של הפלטפורמה וסיים בתוך הזמן הזה:
ב-macOS וב-Linux: Claude Code שולח SIGINT, ואז SIGTERM אם התהליך עדיין רץ 100 אלפיות שנייה אחר כך, ואז SIGKILL אחרי 400 אלפיות שנייה נוספות.
ב-Windows: Claude Code סוגר את stdin של השרת, ואז מסיים את עץ התהליכים של השרת אם התהליך עדיין רץ 300 אלפיות שנייה אחר כך.
לפני v2.1.296, Claude Code ב-Windows סיים את עץ התהליכים של השרת מיד, בלי לסגור קודם את stdin ובלי להמתין.
שרתי WebSocket מחזיקים חיבור דו-כיווני מתמשך, שמתאים לשרתי MCP מרוחקים שדוחפים אירועים ל-Claude בלי בקשה. השתמש ב-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" מקבלת את אותם שדות url, headers, headersHelper, timeout ו-alwaysLoad כמו http. האימות הוא בכותרות בלבד, אז העבר אסימון סטטי ב-headers או צור אחד בזמן החיבור עם headersHelper. הדגל claude mcp add --transport לא מקבל ws.
שרתי MCP לא ייחודיים ל-Claude Code, ולכן הוראות ההתקנה של שרת עשויות להיכתב עבור Claude Desktop, Cursor, או לקוח MCP אחר ולא לכלול פקודת claude mcp add. כדי להוסיף את השרת בכל זאת, חפש בהוראות האלה URL, פקודת הפעלה, או בלוק JSON:
URL כמו https://mcp.example.com/mcp: השרת מרוחק.
פקודת הפעלה כמו npx -y @example/mcp-server: השרת רץ על המחשב שלך.
בלוק JSON של mcpServers: הגדרה שנכתבה לקובץ ההגדרות של לקוח אחר.
כל אחד מאלה הוא אחד מהקלט שארבע האפשרויות ב-התקנת שרתי MCP מקבלות. מצא למטה את הצורה שיש לך כדי להפוך אותה לפקודה ש-Claude Code מקבל. כל פקודה כותבת ל-היקף מקומי אלא אם מוסיפים --scope project או --scope user.
URL אומר שהשרת מרוחק. עבור נקודת קצה https://, הוסף אותה עם --transport http, או עקוב אחרי אפשרות 2 כשההוראות אומרות שנקודת הקצה משתמשת ב-SSE. עבור נקודת קצה wss://, השתמש ב-אפשרות 4 במקום, כי --transport לא מקבל ws:
claude mcp add --transport http example https://mcp.example.com/mcp
אם ההוראות גם נותנות מפתח API או כותרת אסימון, העבר אותה עם --header כמו שמוצג ב-אפשרות 1.
פקודת הפעלה אומרת שהשרת רץ כתהליך stdio מקומי. שים את כל הפקודה אחרי --, כך ש-Claude Code מעביר דגלים כמו -y לפקודה שמפעילה את השרת במקום לקרוא אותם כאפשרויות שלו. העבר משתני סביבה שההוראות מבקשות עם --env, אחרי שם השרת ולפני --:
claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server
בלוק mcpServers שנכתב ללקוח MCP אחר, כמו Claude Desktop, משתמש במפתח העוטף ובצורת הרשומה ש-Claude Code קורא. העבר ל-claude mcp add-json את האובייקט שבתוך mcpServers, לא את העטיפה. שתי רשומות צריכות תיקון קודם:
url בלי type: הוסף "type": "http", "type": "sse", או "type": "ws" כדי להתאים לנקודת הקצה. Claude Code קורא רשומה בלי type כשרת stdio, ולכן רשומת url בלי type נכשלת.
מפתח עם תווים שאינם אותיות, מספרים, מקפים וקווים תחתונים: בחר שם שרת שמשתמש רק בתווים האלה. אחרת המפתח הוא שם השרת.
claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'
הוספת שרתי MCP מהגדרת JSON מכסה escaping של המעטפת ואת הדגל --scope עבור add-json. כדי לשתף את השרת עם הצוות במקום, הוסף --scope project, או הוסף את הרשומה תחת mcpServers ב-.mcp.json בשורש הפרויקט ובצע commit. היקף פרויקט מסביר איך Claude Code טוען ומאשר את הקובץ הזה.
כל פקודת claude mcp add ו-claude mcp add-json מדפיסה שורת Added ... בהצלחה. כדי לבדוק ש-Claude Code התחבר, הרץ claude mcp get <name>. סטטוס שרת מכסה את הסטטוסים שהוא מציג ואת שלב האישור לשרתי .mcp.json.
אחרי ההגדרה, אפשר לנהל את שרתי ה-MCP בפקודות האלה:
# List all configured servers
claude mcp list
# Get details for a specific server
claude mcp get notion
# Remove a server
claude mcp remove notion
# (within Claude Code) Check server status
/mcp
כשמסירים שרת מרוחק, Claude Code מוחק גם את אסימוני ה-OAuth ואת רישום הלקוח ששמר עבור השרת הזה. Claude Code לא מבטל את האסימונים בשרת ההרשאות שהנפיק אותם. כדי לבטל את האסימונים במקום שבו שרת ההרשאות תומך בביטול, הריצו claude mcp logout <name> במעטפת לפני claude mcp remove <name>.
claude mcp list מציג מצב תקינות ליד כל שרת שהוא מציג, למשל ✔ Connected, ! Needs authentication, או ✘ Failed to connect. מצב כשל אומר ש-Claude Code לא הצליח להתחבר לשרת הזה. פקודת הרשימה עצמה לא נכשלה.
המצבים ברשימה הזו מדווחים על החלטת הגדרה ולא על ניסיון חיבור, ולכן Claude Code מדפיס אותם בלי להתחבר לשרת:
⏸ Pending approval (run `claude` to approve): שרת בהיקף פרויקט מתוך .mcp.json שעדיין לא אישרתם. Claude Code מציג אותו גם ב-claude mcp list וגם ב-claude mcp get <name>. הריצו את claude באופן אינטראקטיבי כדי לעיין בו ולאשר אותו.
✘ Rejected (see disabledMcpjsonServers in settings): שרת .mcp.json שרשומת disabledMcpjsonServers דוחה. Claude Code מציג אותו רק ב-claude mcp get <name>.
⊘ Disabled for this project (re-enable via /mcp): שרת שהרשימה disabledMcpServers של הפרויקט מציינת. Claude Code מציג אותו גם ב-claude mcp list וגם ב-claude mcp get <name>. הפעילו מחדש את השרת מלוח /mcp.
✘ Blocked by enterprise managed policy: שרת שאחת ממדיניות הארגון מסרבת לו. Claude Code מציג אותו גם ב-claude mcp list וגם ב-claude mcp get <name>. שרת שנחסם על ידי allowlist, denylist, או הגבלה אחרת ב-managed MCP configuration מוסתר משתי הפקודות. הוא לא מוצג עם המצב הזה. שאלו את מנהל המערכת איזו מדיניות חוסמת את השרת.
claude mcp list ו-claude mcp get קוראים אישורי .mcp.json רק מקובצי הגדרות שלא נכנסו למאגר, עד שנותנים אמון בסביבת העבודה על ידי הרצת claude בתוכה וקבלת תיבת הדו-שיח של אמון בסביבת העבודה. מאגר ששוכפל לא יכול לאשר את השרתים שלו: enableAllProjectMcpServers או enabledMcpjsonServers שנכללו ב-commit של .claude/settings.json של הפרויקט מתעלמים מהם בתיקייה לא מהימנה, והשרת נשאר ב-⏸ Pending approval במקום להיות מחובר ולבדיקת תקינות.
אישורים מהמקורות האלה עדיין חלים בתיקייה לא מהימנה:
~/.claude/settings.json של המשתמש
הגדרות מנוהלות
הגדרות שהועברו עם --settings
Claude Code מחיל גם אישורים מקובץ .claude/settings.local.json שלא במעקב, אבל הוא מריץ את git כדי לבדוק אם הקובץ במעקב, והוא מריץ את הבדיקה הזו רק ב-תיקייה מהימנה. בתיקייה שמעולם לא נתתם בה אמון, Claude Code ממתין לתיבת הדו-שיח של האמון לפני החלת אישורי הקובץ, אלא אם התיקייה היא בית ההגדרות שלכם: תיקיית הבית, או תיקייה שה-.claude שלה הוגדר כ-CLAUDE_CONFIG_DIR. לפני v2.1.207, Claude Code החיל אישורים מקובץ .claude/settings.local.json שלא במעקב גם בתיקייה שמעולם לא נתתם בה אמון.
רשומת disabledMcpjsonServers בכל קובץ הגדרות עדיין דוחה את השרת.
ב-/mcp, כולל תפריט של שרת שם, ובמנהל /plugin, שרת HTTP או SSE מרוחק שהשתמשתם בו בעבר יכול להציג מצב cached כמו cached 2h ago · connects on first use · 5 tools. Claude Code טען את רשימת הכלים של השרת ממטמון הגילוי שלו, שנשמר בסשן קודם, במקום להתחבר בהפעלה, ו-Claude Code מתחבר לשרת בפעם הראשונה ש-Claude קורא לאחד הכלים של השרת. הכלים זמינים מההודעה הראשונה, ולכן אין צורך לעשות דבר. מטמון הגילוי ומצב ה-cached שלו דורשים את Claude Code v2.1.221 או חדש יותר.
מטמון הגילוי כבוי כברירת מחדל, אלא אם פריסה הדרגתית הפעילה אותו עבור החשבון. הגדירו MCP_DISCOVERY_CACHE=1 כדי להפעיל אותו, או 0 כדי להשאיר אותו כבוי גם כשהפריסה ההדרגתית הפעילה אותו. לפני v2.1.238, המטמון היה פעיל כברירת מחדל.
כשבוחרים Disable או Clear authentication מתפריט של שרת ב-/mcp, Claude Code גם מוחק את רשומת המטמון של השרת הזה. Reconnect מוחק אותה גם בשרת מחובר או כושל. בשרת cached, Reconnect מתחבר לשרת עכשיו ושומר את הרשומה. בפעם הבאה ש-Claude Code מתחבר לשרת אחרי מחיקת הרשומה, הוא מביא את רשימת הכלים מהשרת ולא מהמטמון.
כשמצב השרת הוא ✘ Failed to connect, claude mcp list מוסיף את פירוט הכשל לשורת המצב הזו, ו-claude mcp get <name> מציג אותו בשורת Issue:. הפירוט הוא סטטוס HTTP או קוד שגיאה, ועוד כל טקסט שגיאה שהשרת החזיר. תצוגת הפירוט של השרת ב-/mcp כוללת את אותו טקסט שהשרת דיווח בשורת Issue: שלו.
Claude Code מסתיר טקסט דמוי אישורים מהפירוט הזה, והוא לא כולל את כתובת השרת המורחבת, שיכולה לשאת סודות. Claude Code לא מוסיף פירוט למצב ✘ Connection error, כי טקסט החריגה שהוא היה מדפיס שם יכול להכיל את הכתובת הזו.
כשמשלימים אימות מ-/mcp והחיבור עדיין נכשל עם סטטוס HTTP או קוד שגיאת תעבורה, Claude Code מוסיף את הקוד הזה ואת ה-origin של כתובת השרת להודעה שהוא מדפיס אחרי הניסיון. ה-origin הוא הסכמה והמארח, ועוד הפורט כשהכתובת מציינת אחד, למשל https://mcp.example.com.
הנתיב והשאילתה לא מופיעים בהודעה הזו.
עבור שרת ב-היקף local, project, או user, או בהגדרת MCP מנוהלת, ה-origin מציג את המארח כפי שנכתב בהגדרה הזו, ולכן הפניה ${VAR} במארח לא מורחבת בהודעה.
עבור כשל בלי סטטוס או קוד שגיאה, Claude Code מציג את טקסט השגיאה בלי ה-origin.
שרת מרוחק שההגדרה שלו מכילה url ריק מוצג כ-not configured ב-/mcp, ב-claude mcp list, ובמנהל /plugin, ו-Claude Code לא מנסה להתחבר אליו. תוסף יכול לכלול רשומת מציין מקום כזו עבור מחבר שתגדירו מאוחר יותר, ולכן Claude Code לא מדווח עליו כשגיאה או כבעיית הגדרה. תצוגת הפירוט של השרת ב-/mcp כתובה No URL configured for this server. הגדירו את url של הרשומה כדי לחבר אותו.
Claude Code מזהיר על בעיות ההגדרה שלמטה. כל רשומה אומרת מה Claude Code בודק ואיך לנקות את האזהרה:
רווח לבן מוסתר: Claude Code מזהיר כשערך בהגדרת MCP נושא רווח לבן מוסתר בהתחלה או בסוף, שלעתים קרובות מגיע מהדבקת אסימון עם שורה חדשה בסוף. Claude Code בודק את command, את url, כל רשומת args, ואת הערכים ושמות המפתחות תחת env ו-headers. Claude Code מציג את האזהרה בפלט claude mcp list וב-/mcp, ומציין את השדות המושפעים בלי להדהד את הערכים שלהם, למשל Leading or trailing whitespace in: headers.Authorization. Claude Code לא חותך את הרווח הלבן ומשתמש בערכים בדיוק כפי שנכתבו, ולכן ערכו את ההגדרה כדי להסיר אותו.
אותו שם ביותר מהיקף אחד: אם מגדירים את אותו שם שרת ביותר מ-היקף אחד עם נקודות קצה שונות, Claude Code מזהיר על ההתנגשות בפלט claude mcp list וב-/mcp. Claude Code שומר כניסות OAuth לפי נקודת קצה, ולכן כשמאמתים את ההגדרה שנטענת בפרויקט אחד, עדיין צריך להיכנס בנפרד בפרויקט שבו נטענת הגדרה אחרת. השאירו את נקודת הקצה הרצויה והסירו את האחרות עם claude mcp remove <name> --scope <scope>. באזהרה, Claude Code מצטט את נקודת הקצה של כל היקף כפי שנכתבה בהגדרה, עם הפניות ${VAR} לא מורחבות, ולכן הוא לא מציג ערך שנפתר כמו מפתח API.
שמות שמורים: Claude Code שומר את השמות של השרתים המובנים שלו, כולל workspace, claude-in-chrome, computer-use, Claude Preview, ו-Claude Browser. אם ההגדרה מגדירה שרת בשם שמור, Claude Code מדלג עליו בזמן הטעינה ומציג אזהרה שמבקשת לשנות את השם. claude mcp add דוחה שם שמור עם שגיאה. Claude Preview ו-Claude Browser שניהם שמות לשרת המובנה שחלונית התצוגה המקדימה של אפליקציית שולחן העבודה של Claude Code משתמשת בו.
משתנה סביבה חסר: אם הפניית ${VAR} בהגדרת שרת מציינת משתנה שלא מוגדר ואין לו :-default, Claude Code מזהיר בפלט claude mcp list וב-/mcp, מציין את המשתנה, ועדיין טוען את השרת עם טקסט ${VAR} לא מורחב. הגדירו את המשתנה או הוסיפו גיבוי ${VAR:-default}. ב-url וב-headers של שרת מרוחק, חלק ממשתני האישורים נקראים כריקים במקום זאת, בלי אזהרה.
לוח /mcp מציג את מספר הכלים ליד כל שרת מחובר, ומסמן שרתים שמפרסמים את יכולת הכלים אבל לא חושפים כלים.
אם הבקשה צריכה כלים משרת שעדיין מתחבר ברקע, Claude ממתין לשרת הזה לפני שהוא ממשיך. אופן ההמתנה תלוי בהגדרה:
עם חיפוש כלים, ברירת המחדל: ההמתנה מתרחשת בתוך הקריאה ל-ToolSearch.
בלי חיפוש כלים: Claude משתמש בכלי WaitForMcpServers. הגדרות בלי חיפוש כלים כוללות ENABLE_TOOL_SEARCH=false ומודל מוקדם מ-Claude Opus 4.5, Claude Sonnet 4.5, ו-Claude Haiku 4.5 ב-Agent Platform של Google Cloud. עבור שער ANTHROPIC_BASE_URL, ראו Tool search through an LLM gateway.
ב-פריסה שמתארחת ב-Azure של Microsoft Foundry: Claude מתחיל במסלול חיפוש הכלים ולא עם WaitForMcpServers, כי Claude Code מגלה את הדחייה בצד השרת של הפריסה רק מה-API. אחרי ש-Claude Code מעביר את הפריסה הזו ל-טעינה מראש, כלים משרת שמסיים להתחבר נעשים זמינים בבקשה הבאה של Claude.
כשחיפוש כלים מופעל, כששרת מסיים להתחבר בזמן ש-Claude עובד, Claude Code מציג ל-Claude את שמות הכלים של השרת בבקשה הבאה שלו באותו תור. Claude יכול אז לחפש את הכלים האלה ולקרוא להם בלי להמתין להודעה הבאה.
אחרי שמחדשים סשן, Claude יכול לקרוא לכלי מהשיחה השמורה בזמן ששרת ה-MCP של הכלי עדיין מתחבר. בזמן שהשרת בניסיון החיבור הראשון שלו, Claude Code מחזיק את הקריאה עד 10 שניות ומריץ אותה ברגע שהכלי זמין. אם השרת לא מתחבר בזמן, או שהוא כבר מנסה שוב אחרי ניסיון שנכשל, הקריאה נכשלת עם שגיאת הכליNo such tool available.
כבו שרת בלוח /mcp כדי לעצור את Claude Code מלהתחבר אליו בלי לאבד את ההגדרה שלו. Claude Code עדיין מציג את השרת ב-/mcp, מסומן כמושבת.
כשמחליפים מצב של שרת, Claude Code רושם את הבחירה לפי פרויקט ב-~/.claude.json, באחת משתי רשימות שמכסות קבוצות נפרדות של שרתים:
disabledMcpServers: רשימת opt-out עבור שרתים שהמשתמש הגדיר, שרתי תוספים, שרתים שהארגון מספק דרך הגדרות מנוהלות, מחברי claude.ai ש-Claude Code מביא בעצמו, ושרתים מובנים שברירת המחדל שלהם היא פעיל. Claude Code לא מתחבר לשרת שמציינים כאן. כשמשביתים מחבר claude.ai עם מתג /mcp לפי פרויקט שמתואר ב-Disable claude.ai connectors, Claude Code כותב אותו לרשימה הזו תחת שם התצוגה שלו, למשל claude.ai Slack.
enabledMcpServers: רשימת opt-in עבור שרתים מובנים שברירת המחדל שלהם היא כבוי, כמו computer-use. Claude Code מתחבר לשרת שברירת המחדל שלו כבויה רק כשמציינים אותו כאן.
Claude Code מתייעץ בדיוק באחת משתי הרשימות עבור כל שרת, ולכן אף רשימה לא גוברת על האחרת. אם מוסיפים שרת רגיל ל-enabledMcpServers, או שרת מובנה שברירת המחדל שלו כבויה ל-disabledMcpServers, Claude Code מתעלם מהרשומה.
Claude Code מתחבר לשרתי MCP דרך אחת משתי סביבות ריצה של לקוח. סביבת הריצה v1 בנויה על MCP TypeScript SDK 1.x. סביבת הריצה v2 היא אותו קוד על MCP TypeScript SDK 2.0, שמוסיף את גרסת פרוטוקול MCP 2026-07-28. שאר הדף חל על שתי סביבות הריצה, מלבד מקום שבו סעיף מציין את סביבת הריצה v2.
Claude Code בוחר סביבת ריצה בכל פעם שמפעילים אותו ושומר אותה עד היציאה. בסשנים שבהם הוא מביא דגלי תכונות, הוא משתמש בסביבת הריצה v2 ב-Claude Code v2.1.232 או חדש יותר.
בסשנים שבהם הוא לא מביא דגלי תכונות, Claude Code משתמש בסביבת הריצה v2 כברירת מחדל ב-Claude Code v2.1.274 או חדש יותר:
סשנים ב-Amazon Bedrock, Claude Platform on AWS, Agent Platform של Google Cloud, או Microsoft Foundry, אלא אם פלטפורמת מארח שמטמיעה את Claude Code מגדירה CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST
סשנים שבהם מכבים טלמטריה או הבאת דגלי תכונות, למשל עם DISABLE_TELEMETRY
ב-v2, Claude Code גם:
שואל שרתי HTTP, stdio, ומחברי claude.ai אם הם תומכים בגרסה החדשה יותר ומשתמש בה עם אלה שתומכים. זה כולל את המחברים של סשני ענן ו-Remote Control. Claude Code מתחבר לכל שרת אחר כמו ש-v1 עושה.
לא רושם שרת channel שמתחבר בגרסה החדשה יותר, כי הגרסה הזו לא יכולה לשאת הודעות channel.
נכשל ב-כניסת MCP OAuth שתגובת ההרשאה שלה מציינת issuer לא צפוי.
שולח אישורי MCP OAuth רק לנקודת קצה של אסימון שמוגשת דרך HTTPS או ב-localhost, 127.0.0.1, או ::1. הכניסה נכשלת עבור שרת שנקודת הקצה של האסימון שלו היא http:// רגיל בכל מקום אחר, כמו מכשיר ברשת המקומית. ראו Refusing to send credentials to non-https token endpoint.
Anthropic יכולה להשאיר שרת מסוים על הפרוטוקול המוקדם יותר, או מחוץ לזרם הזה, עם דגל תכונה ש-Claude Code מביא.
בזמן הריצה v2, Claude Code מקבל התראות list_changed משרת שנמצא בגרסת הפרוטוקול החדשה יותר דרך זרם שהוא מחזיק פתוח. כשהזרם נסגר, Claude Code פותח אותו מחדש, עם שני גבולות:
הזרם נסגר שוב בתוך 10 שניות: Claude Code פותח אותו מחדש עד שלוש פעמים, ואז מפסיק עבור החיבור הזה.
הזרם נשאר פתוח יותר מ-10 שניות ואז נסגר, כמו שקורה בדרך כלל בזרמים אל מארחים serverless: אחרי חמש פתיחות מחדש בשעה, Claude Code ממתין כשש שעות לפני הפתיחה הבאה.
עד שהזרם נפתח מחדש, נשמרים אצלכם הכלים, ה-prompts והמשאבים האחרונים שנמשכו מהשרת. כדי לקלוט את השינויים שלו מוקדם יותר, חברו מחדש את השרת מתוך /mcp.
Claude Code מחבר מחדש שרת מרוחק שמתנתק באמצע סשן, ומנסה שוב את החיבור הראשון של שרת HTTP או SSE אחרי שגיאה חולפת. עבור שרת stdio, ראו שרתי stdio שיוצאים או נכשלים בהפעלה.
Claude Code מנסה קודם לחבר מחדש שרת מרוחק שהתנתק עד חמש פעמים עם השהיה מעריכית, שמתחילה בהשהיה של שנייה אחת ומכפילה אותה בכל פעם:
בסשן אינטראקטיבי: /mcp מציג את השרת כממתין בזמן ש-Claude Code מתחבר מחדש. אחרי חמישה ניסיונות שנכשלו, Claude Code מסמן את השרת כנכשל, או כזקוק לאימות כשהשרת צריך הרשאה מחדש. כשהוא מסמן את השרת כנכשל, מופיעה התראה MCP server "<name>" disconnected · open /mcp to reconnect. אפשר לנסות שוב ידנית מתוך /mcp.
בהרצות claude -p ובסשנים של Agent SDK: Claude Code מבצע את אותם חמישה ניסיונות, בלי לוח /mcp שמציג אותם. אם כל החמישה נכשלים, ההרצה ממשיכה בלי הכלים של השרת:
אחרי שגיאה חולפת, כמו תגובת 5xx או timeout: Claude Code ממשיך לנסות שוב שרת HTTP או SSE ברקע. הניסיונות נמשכים עד כחצי שעה, והכלים של השרת חוזרים להיות זמינים כשאחד מהם מתחבר. עד אז, סשן Agent SDK מדווח על הסטטוסfailed, והקוד שלכם יכול לחבר מחדש את השרת. כדי לחבר אותו מחדש ב-claude -p, התחילו את ההרצה שוב.
כשהחיבור הראשון של שרת HTTP או SSE נכשל עם שגיאה חולפת, כמו תגובת 5xx, connection refused או timeout, Claude Code מנסה שוב עד שלוש פעמים. אם החיבור עדיין נכשל, Claude Code מסמן את השרת כנכשל.
החיבור הראשון של שרת WebSocket. כדי לנסות אותו שוב בסשן טרמינל אינטראקטיבי, בחרו Reconnect מתפריט השרת ב-/mcp
שגיאת אימות או שגיאת not-found, כי נדרש שינוי הגדרות כדי לפתור אותה. כש-headersHelper הוא המקור היחיד של השרת לכותרת Authorization, Claude Code מנסה שוב שגיאת אימות בכל זאת, כי הוא מריץ מחדש את ה-helper בכל ניסיון ויכול לקלוט credential טרי
כדי להפעיל שוב שרת stdio, קראו את העמודה שמתאימה למה שקרה לו. מצאו את השורה שלכם לפי האופן שבו אתם מריצים את Claude Code: סשן אינטראקטיבי, הרצת claude -p, או סשן Agent SDK.
איך מריצים את Claude Code
תהליך השרת יוצא באמצע הסשן
החיבור הראשון של השרת נכשל
סשן אינטראקטיבי
Claude Code מסמן את השרת כנכשל. כדי להפעיל אותו שוב, בחרו Reconnect מתפריט השרת ב-/mcp
Claude Code מסמן את השרת כנכשל. כדי להפעיל אותו שוב, בחרו Reconnect מתפריט השרת ב-/mcp
הרצת claude -p
Claude Code מפעיל את השרת שוב בפעם הבאה ש-Claude קורא לאחד הכלים של השרת, והקריאה רצה ברגע שהשרת מתחבר
ההרצה ממשיכה בלי הכלים של השרת. כדי ש-Claude Code ינסה את החיבור שוב, התחילו את ההרצה שוב. כשתוסף מספק את השרת, הרצות חדשות מדלגות על החיבור למשך 15 דקות אחרי כשל, אז המתינו זמן זה קודם או נסו שוב מוקדם יותר
סשן Agent SDK
Claude Code מפעיל את השרת שוב בפעם הבאה ש-Claude קורא לאחד הכלים של השרת, והקריאה רצה ברגע שהשרת מתחבר
אחרי ששרת מתחבר, Claude Code שולח אליו בקשות גילוי יכולות כמו tools/list, prompts/list ו-resources/list. Claude Code מנסה שוב את הבקשות האלה עד שלוש פעמים עם השהיה קצרה אחרי שגיאת רשת או שרת חולפת. הוא לא מנסה שוב שגיאות אימות, תגובות 4xx או timeouts של בקשה.
כדי לנסות שוב כל שרת שנכשל או זקוק לאימות, הריצו /mcp reconnect all בשורת הפקודה של Claude Code בסשן טרמינל אינטראקטיבי. זה דורש Claude Code v2.1.284 או חדש יותר. גרסאות קודמות מדפיסות MCP server "all" not found.
האם Claude Code מודיע ל-Claude על שרת מוגדר שנכשל בחיבור תלוי בחיפוש כלים, שפועל כברירת מחדל:
עם חיפוש כלים, Claude Code אומר ל-Claude איזה שרת נכשל ומה שגיאת החיבור שלו, כך ש-Claude מדווח על כשל החיבור בתשובה שלו. Claude Code כולל את אותו מידע בתוצאות ToolSearch שלא מוצאות כלי תואם.
שרת MCP יכול גם לדחוף הודעות ישירות לתוך הסשן שלכם כדי ש-Claude יוכל להגיב לאירועים חיצוניים כמו תוצאות CI, התראות ניטור או הודעות צ'אט. כדי להפעיל את זה, השרת שלכם מצהיר על היכולת claude/channel ואתם מפעילים את האפשרות עם הדגל --channels בהפעלה. ראו Channels כדי להשתמש בערוץ נתמך רשמית, או Channels reference כדי לבנות ערוץ משלכם.
בזמן הריצה v2, שרת ערוץ שמנהל משא ומתן על גרסת פרוטוקול MCP 2026-07-28 לא יכול למסור הודעות ערוץ, ולכן Claude Code לא רושם אותו כערוץ. שרת ערוץ שלא תומך בגרסה הזאת מתחבר ב-handshake המוקדם יותר ונרשם כמו קודם.
Claude Code מבקש משרתי stdio את הגרסה הזאת כברירת מחדל. כדי להשאיר שרת ערוץ stdio על ה-handshake המוקדם יותר, הגדירו את MCP_PROTOCOL_NEGOTIATION ל-legacy, מה שמשאיר כל שרת עליו.
[!TIP]
טיפים:
השתמשו בדגל -s או --scope כדי לציין איפה ההגדרה נשמרת:
local (ברירת מחדל): זמין רק לכם בפרויקט הנוכחי
project: משותף עם כולם בפרויקט דרך הקובץ .mcp.json
user: זמין לכם בכל הפרויקטים
הגדירו משתני סביבה עם הדגלים -e או --env (לדוגמה, -e KEY=value)
הדגלים --transport ו---header מקבלים גם את הצורות הקצרות -t ו--H
הגדירו timeout להפעלת שרת MCP באמצעות משתנה הסביבה MCP_TIMEOUT (לדוגמה, MCP_TIMEOUT=10000 claude קובע timeout של 10 שניות)
הגדירו timeout להרצת כלי לכל שרת על ידי הוספת שדה timeout באלפיות שנייה לרשומת .mcp.json של השרת, לדוגמה "timeout": 600000 לעשר דקות. זה דורס את משתנה הסביבה MCP_TOOL_TIMEOUT עבור השרת הזה בלבד
Claude Code מציג אזהרה כשפלט כלי MCP עובר 10,000 טוקנים ומגביל את הפלט ל-25,000 טוקנים כברירת מחדל. כדי לשנות את מגבלת הטוקנים, הגדירו את משתנה הסביבה MAX_MCP_OUTPUT_TOKENS, לדוגמה MAX_MCP_OUTPUT_TOKENS=50000. סף האזהרה קבוע. אלא אם השרת מעלה את המגבלה של הכלי עצמו, תוצאות טקסט מוצלחות שאורכן יותר מ-50,000 תווים נשמרות לקובץ בלי תלות במשתנה הזה. ראו מגבלות פלט MCP ואזהרות
השתמשו ב-/mcp כדי לאמת מול שרתים מרוחקים שדורשים אימות OAuth 2.0
ה-timeout לכל שרת הוא מגבלת שעון קשיחה לכל קריאת כלי, והתראות התקדמות מהשרת לא מאריכות אותה. ערכים מתחת ל-1000 מתעלמים מהם והם עוברים אל MCP_TOOL_TIMEOUT, או אל ברירת המחדל שלו של כ-28 שעות כשהמשתנה לא מוגדר. עבור שרת HTTP, SSE או מחבר claude.ai יש גם טיימר שני לכל בקשה, שמכסה כל בקשה עד בית התגובה הראשון של השרת. Claude Code קובע את הטיימר הזה לגדול מבין שלושה ערכים: 60 שניות, ה-timeout של הכלי שחל על השרת, ו-MCP_TIMEOUT. ברירת המחדל של 28 שעות כש-MCP_TOOL_TIMEOUT לא מוגדר לא נכנסת להשוואה הזאת, וערך מתחת ל-60 שניות לא מקצר את הטיימר. לשרתי stdio ו-WebSocket אין טיימר לכל בקשה.
timeout לכל שרת של לפחות 1000 משמש גם כסף תחתון ל-timeout של חוסר פעילות שמתואר בהמשך: Claude Code אף פעם לא מבטל את קריאות הכלי של השרת הזה בגלל חוסר פעילות מוקדם יותר מה-timeout לכל שרת.
קריאת כלי לשרת MCP שלא שולח תגובה ולא התראת התקדמות במשך חלון חוסר הפעילות מבוטלת עם שגיאה במקום להמתין למגבלת השעון. ה-timeout של חוסר פעילות חל על כל סוג שרת חוץ משרתי IDE ושרתי SDK בתוך התהליך. חלון חוסר הפעילות הוא כברירת מחדל חמש דקות לשרתי HTTP, SSE, WebSocket ומחבר claude.ai, ו-30 דקות לשרתי stdio.
הגדירו את משתנה הסביבה CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT באלפיות שנייה כדי לשנות את חלון חוסר הפעילות, או הגדירו אותו ל-0 כדי לבטל את הבדיקה.
ה-timeouts האלה מגבילים כמה זמן קריאה יכולה לרוץ, ולא תמיד כמה זמן היא חוסמת את הסשן: קריאה בשיחה הראשית שרצה מעבר לשתי דקות עוברת קודם למשימת רקע. ראו העברה אוטומטית לרקע של קריאות כלי ארוכות.
אם תצוגת הפרטים של קריאת רקע ב-/tasks מציגה runs on the server; survives exiting this session, ראו משימות MCP שרצות על השרת.
קריאת כלי MCP בשיחה הראשית שעדיין רצה אחרי שתי דקות עוברת למשימת רקע במקום לחסום את הסשן. Claude מקבל את מזהה המשימה מיד וממשיך לעבוד, והתוצאה מגיעה כהתראת משימה כשהקריאה מסתיימת.
המשימה מופיעה ב-/tasks, שם אפשר גם לעצור אותה, והיא לא שורדת יציאה מהסשן. הרשומה של המשימה מציגה את ההתקדמות האחרונה שהשרת דיווח. אם עוצרים את המשימה, Claude Code מבטל את הקריאה ואומר ל-Claude שלא תגיע תוצאה. עצירה לא מבטיחה שהשרת נעצר: ייתכן שהוא כבר ביצע חלק מהעבודה, או שהוא עדיין יסיים אותה.
קריאות מסוכני משנה. Claude Code מעביר לרקע רק קריאות מהשיחה הראשית
קריאות לשרתי IDE
קריאות במצב לא אינטראקטיבי, אלא אם CLAUDE_AUTO_BACKGROUND_TASKS מוגדר ל-1, כי הרצה חד פעמית יכולה להסתיים לפני שהתוצאה מגיעה
קריאה שממתינה לתיבת elicitation פתוחה לא עוברת לרקע כל עוד התיבה פתוחה. השרת חסום על הקלט שלכם, הוא לא איטי, ולכן Claude Code דוחה את המעבר עד שהתיבה נסגרת.
משימת MCP היא עבודה ארוכה, כמו ייצוא דוח או בנייה, ששרת MCP מריץ בעצמו באמצעות הרחבת המשימות של MCP. קריאת הכלי של Claude חוזרת ברגע שהשרת מקבל את העבודה, ולכן Claude ממשיך לעבוד אלא אם גורמים ל-Claude להמתין. כשהעבודה מסתיימת, התמליל מדווח על כך ו-Claude מקבל את התוצאה. בקשו אותה מ-Claude.
בינתיים, הכותרת התחתונה מציגה ספירה כמו 1 MCP task, ו-Claude Code עוקב אחרי המשימה על ידי בדיקת הסטטוס שלה מול השרת. משימה בשרת מרוחק ממשיכה לרוץ אחרי היציאה. כדי לעקוב אחריה שוב, חדשו את אותה שיחה.
[!NOTE]
משימות MCP נמצאות בבטא ציבורית ב-CLI של Claude Code ודורשות את Claude Code מגרסה v2.1.304 ואילך. מה נדרש מקריאה כדי שתהפוך למשימת MCP מפרט את השיחות והשרתים שמקבלים אותן.
כדי לעצור משימה שרצה, בחרו אותה ב-/tasks ולחצו על x, או בקשו זאת מ-Claude. Claude Code מפסיק לעקוב אחרי המשימה ומבקש מהשרת לבטל אותה, אם כי השרת עשוי עדיין לסיים אותה. חברו מחדש שרת מנותק מ-/mcp קודם, אחרת לא יוצאת בקשת ביטול ו-Claude Code שוכח את המשימה ולא יכול לעקוב אחריה שוב. לחיצה על Esc לא עוצרת משימת רקע.
משימה שרצה יכולה לפתוח דיאלוג elicitation כדי לבקש מכם קלט. כל עוד /tasks פתוח, הדיאלוג נשאר מוסתר, ולכן סגרו את /tasks כדי לענות. סירוב או לחיצה על Esc הם תשובה לשרת, והוא מחליט אם המשימה ממשיכה.
בשיחה לא אינטראקטיבית, Claude Code מבקש מהשרת לבטל משימה שמבקשת קלט, בלי להריץ את הוקי Elicitation שלכם ובלי לקרוא ל-callback onElicitation של Agent SDK.
משימה בשרת מרוחק ממשיכה לרוץ אחרי היציאה. התהליך של שרת stdio נעצר כש-Claude Code יוצא, אם כי המשימות שלו מציגות runs on the server; survives exiting this session ב-/tasks. אלא אם התיעוד של השרת הזה אומר שהעבודה ממשיכה אחרי התהליך, תנו למשימות האלה להסתיים או עצרו אותן ב-/tasks קודם.
מצב
מה קורה למשימה
מה אפשר לעשות
מריצים /clear או /branch, או /resume לשיחה אחרת
כל עוד Claude Code נשאר פתוח, התוצאה מגיעה לשיחה הנוכחית
אחרי יציאה, claude --resume לשיחה שבה המשימה התחילה
יוצאים מ-Claude Code
אף אפשרות יציאה לא מבטלת משימה של שרת מרוחק, גם כשדיאלוג היציאה מציג אותה תחת The following will stop when you exit:
עוצרים אותה ב-/tasks קודם, או מחדשים את אותה שיחה אחר כך
חוזרים לשיחה של המשימה באופן אינטראקטיבי: claude --resume, claude --continue, או /resume
ברגע שהשרת מתחבר, Claude Code עוקב אחרי המשימה שוב, ו-Claude מקבל את התוצאה אם היא הסתיימה בינתיים והשרת עדיין מכיר אותה
משאירים את שם השרת ואת הגדרות החיבור בלי שינוי
מחדשים את השיחה של המשימה עם --resume או --continue בהרצה חד פעמית claude -p "<prompt>"
ההרצה הזו לא עוקבת אחרי המשימה
מחדשים באופן אינטראקטיבי, או עם --input-format stream-json
השאירו את הקלט של שיחת Agent SDK או stream-json פתוח, כי ההרצה לא ממתינה למשימות MCP אחרי שהקלט נסגר. הרצה חד פעמית claude -p "<prompt>" לא מקבלת משימות MCP.
ההודעות האלה, ברשומת /tasks של משימה או בשורת הסיום שלה בתמליל, אומרות ש-Claude Code לא מצליח להגיע לשרת או למשימה. כל עוד אחת מוצגת ב-/tasks, העבודה עשויה עדיין לרוץ: Claude Code משאיר אותה ומוסיף לבדוק. הודעות 300s והודעות התצורה נשארות ברשומה גם אחרי שהקשר חוזר.
הודעה
מה קורה
מה אפשר לעשות
reconnecting…
השרת לא ענה מאז חידוש, או שבדיקות סטטוס לא מקבלות תשובה
אם זה נשאר, התחברו מחדש מ-/mcp
needs a sign-in to <server>
השרת סירב לבדיקת סטטוס
התחברו מ-/mcp
status requests come back with errors; retrying…
השרת, או פרוקסי לפניו, עונה לבדיקות סטטוס בשגיאות
המתינו בזמן ש-Claude Code מנסה שוב
server '<name>' did not reconnect within 300s
אין בדיקה שנענתה במשך חמש דקות, למשל כשהחיבור למטה או שהשרת מושבת
התחברו מחדש מ-/mcp
server '<name>' asked for a sign-in, and none was accepted within 300s
אחרי חמש דקות השרת עדיין רוצה התחברות
התחברו מ-/mcp
status requests to server '<name>' came back with errors, and none succeeded in 300s
חמש דקות של תשובות שגיאה
בדקו את תקינות השרת עצמו או את היומנים שלו
server '<name>' is not configured in this session; the task may still be running on it
לשיחה אין שרת בשם הזה, למשל הוא הוסר, שונה שמו, או הושמט מ---mcp-config, או שמחבר claude.ai עדיין נטען
שחזרו את השרת תחת אותו שם, ואז חדשו את השיחה שוב. למחבר בטעינה, כלום: Claude Code עוקב אחרי המשימה ברגע שהוא מופיע
הודעה שמתחילה ב-server '<name>' was reconfigured to a different transport since this task was created
קיים שרת בשם הזה עם הגדרות חיבור שהשתנו מאז שהמשימה התחילה, כמו ה-URL, הפקודה, args, env, headers, או timeout
שחזרו את ההגדרות הקודמות, ואז חדשו את השיחה שוב
the server rejected this task's id; asking again…
השרת אומר שהוא לא מכיר את מזהה המשימה. Claude Code ממשיך לשאול עד חמש דקות
המתינו: ההודעה נמחקת אם השרת מזהה את המזהה שוב, או שמופיעה השורה outcome unknown.
שורת תמליל שמסתיימת ב-outcome unknown., בצורה אחת expired on the server: outcome unknown.
השרת דחה את המזהה או סירב בשגיאה קבועה אחרת, ו-Claude Code הפסיק לעקוב אחרי המשימה
קריאה שנייה עלולה לחזור על העבודה. לפני קריאה לכלי שוב, בררו מהשרת מה נעשה, למשל על ידי בקשה מ-Claude להשתמש בכלים האחרים של השרת
כברירת מחדל, למשימה ברקע אין מגבלת זמן של Claude Code. מגבלות הזמן של קריאת כלי, כולל מגבלת שעון הקיר ופסק הזמן של חוסר פעילות, חלות עד שהשרת עונה לקריאה עם המשימה. אם גורמים ל-Claude להמתין, הן חלות על כל המשימה. בדיקות סטטוס שנענו נחשבות לפעילות לפסק הזמן של חוסר פעילות.
CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND שמוגדר ל-1: Claude ממתין לתוצאה של משימה. כל עוד העברה אוטומטית לרקע פועלת, הקריאה עוברת אחרי שתי דקות כברירת מחדל, כך שמשימות קצרות מסתיימות במקומן ומשימות ארוכות לא חוסמות אתכם. הקריאה שהועברה היא קריאת רקע רגילה ולא משימת MCP. היא לא שורדת יציאה מהשיחה
אם מגדירים CLAUDE_CODE_DISABLE_BACKGROUND_TASKS ל-1 או מתחילים במצב bare, זה לבד לא גורם ל-Claude להמתין למשימות MCP. הדוגמה הזו מגדירה CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS ל-0, כך ש-Claude ממתין לכל קריאת כלי MCP:
אם בונים שרת MCP, אפשר לענות ל-tools/call ארוך באמצעות משימה. הרחבת המשימות של MCP מגדירה את ההודעות ששולחים. בחיבור בגרסת פרוטוקול 2026-07-28, כל בקשה נושאת את יכולות הלקוח של Claude Code ב-params._meta["io.modelcontextprotocol/clientCapabilities"], עם "io.modelcontextprotocol/tasks": {} תחת extensions. בקשת tools/call שלא יכולה להפוך למשימה משמיטה את ההרחבה הזו.
ענו במשימה רק כשהבקשה נושאת את ההרחבה, אחרת Claude מקבל את שגיאת הכלי Unsupported result type 'task' for tools/call. Claude מקבל את אותה שגיאה כשחסרים taskId, status, createdAt, lastUpdatedAt, או ttlMs. אובייקט המשימה הוא ה-result של JSON-RPC בתגובת tools/call שלכם, לא צריך מערך content, וכאן כולל את statusMessage ו-pollIntervalMs האופציונליים:
הגדירו אותו ל-"task" כדי לסמן את התשובה כמשימה. בלעדיו, Claude Code קורא את התשובה כתוצאה רגילה
taskId
חובה. לכל היותר 128 תווי ASCII להדפסה בלי רווחים, אחרת Claude מקבל שגיאת כלי שמתחילה ב-MCP server "<name>" returned a malformed task handle for tool "<tool>". שמרו על מזהה שאפשר לענות עליו בין חיבורים, כי אחרי חידוש Claude Code שואל עליו בחיבור חדש
status
חובה. אחד מ-working, input_required, completed, failed, או cancelled. ערך אחר נותן את השגיאה Unsupported result type
createdAt, lastUpdatedAt, ttlMs
חובה, ו-ttlMs יכול להיות null. Claude Code לא מוותר על משימה כי ה-ttlMs שלה עבר
pollIntervalMs
אופציונלי, אבל לא null. אלפיות שנייה בין בקשות tasks/get, מוגבל לטווח שבין 250 ל-30000. Claude Code משתמש ב-2000 כשהשדה חסר, וקורא את הערך שוב מכל תגובת tasks/get
statusMessage
אופציונלי. /tasks מציג את הערך מתגובת tasks/get האחרונה שלכם, לא מהתשובה הראשונה הזו, ותגובה שמשמיטה את השדה מוחקת אותו. הודעת סטטוס מ-Claude Code יכולה לתפוס את מקומו
בשרת HTTP או מחבר claude.ai, תשובת המשימה חייבת להתחיל בתוך טיימר הבקשה, אז קבלו את העבודה וענו קודם, ואחר כך בצעו את העבודה.
מיד אחרי תשובת המשימה, Claude Code שולח tasks/get עם { "taskId": ... }, ואז חוזר על זה פעם אחת בכל מרווח סקר. הרחבת המשימות דורשת שהתגובה שלכם תישא "resultType": "complete" יחד עם taskId, status, createdAt, lastUpdatedAt, ו-ttlMs. ttlMs יכול להיות null, ו-statusMessage ו-pollIntervalMs אופציונליים. הדוגמה הזו מדווחת שהבנייה הסתיימה:
נותן ל-Claude את תוצאת tools/call הרגילה באובייקט result ברמה העליונה. isError: true בתוכו מדווח ככישלון
failed
אומר ל-Claude את message של אובייקט error ברמה העליונה { code, message, data }, שהרחבת המשימות דורשת במשימה שנכשלה. בלי אותו message, Claude מקבל statusMessage, או אחרת Task failed
cancelled
אומר ל-Claude את statusMessage, או אחרת Task was cancelled by the server
input_required
קורא את inputRequests, אובייקט שממפה מפתח שאתם בוחרים אל { method, params }. Claude Code עונה לכל מפתח פעם אחת דרך tasks/update עם { taskId, inputResponses }, כאשר inputResponses ממפה את אותו מפתח לתוצאת הבקשה הזו. מתעלמים ממפתחות מעבר ל-16 למשימה
שיטות ב-inputRequests
elicitation/create מוגש רק בשיחות מסוף אינטראקטיביות, ו-roots/list בכל מקום. כש-Claude Code לא יכול להגיש בקשה, הוא מבקש מהשרת לבטל את המשימה
ערך status אחר
Claude Code מבקש מהשרת לבטל את המשימה ומדווח עליה ל-Claude ככישלון
שגיאת JSON-RPC -32602
נקראת כמזהה משימה לא ידוע. למשימה ברקע, Claude Code ממשיך לשאול עד חמש דקות, ואז מדווח את התוצאה ל-Claude כלא ידועה
tasks/cancel
נשלח, למשל, כש-Claude או האדם עוצרים את המשימה בזמן שהשרת מחובר. לא נשלח ביציאה
tasks/result, tasks/list, notifications/tasks
לא בשימוש, לכן שימו את התוצאה בתגובות tasks/get שלכם
תוספים יכולים לכלול שרתי MCP שמספקים כלים ואינטגרציות כשמפעילים את התוסף.
איך שרתי MCP של תוספים עובדים:
תוספים מגדירים שרתי MCP בקובץ .mcp.json בשורש התוסף, או בתוך plugin.json
כשמפעילים תוסף, Claude Code מפעיל את שרתי ה-MCP שלו אוטומטית
Claude Code מציע כלי MCP של תוספים לצד כלי MCP שהוגדרו ידנית
מוסיפים ומסירים שרתי תוסף על ידי התקנת התוסף או הסרתו, לא באמצעות פקודות /mcp. עדיין אפשר לכבות שרת תוסף מותקן ב-/mcp, וזה עוצר את Claude Code מלהתחבר אליו בלי להסיר את התוסף
מחזור חיים אוטומטי: השרתים מתחברים ומתנתקים בנקודות האלה:
בהפעלת סשן, Claude Code מחבר אוטומטית את השרתים של תוספים מופעלים. ב-/mcp, שרת תוסף מרוחק (HTTP או SSE) שכבר השתמשתם בו יכול להציג את הסטטוס cached במקום זאת. Claude Code מחבר אותו כש-Claude קורא לראשונה לאחד הכלים שלו. כשחיבור של שרת תוסף מסוג stdio נכשל לפני פחות מ-15 דקות, Claude Code מדלג על החיבור
אם מפעילים או משביתים תוסף במהלך סשן, Claude Code מחבר או מנתק את שרתי ה-MCP שלו כשהשינוי חל. החלת שינויי תוספים בלי הפעלה מחדש מתארת מתי זה קורה. בסשן בלי מסוף אינטראקטיבי, /reload-plugins לא מחבר ולא מנתק שרתי MCP של תוספים. השינויים האלה נכנסים לתוקף בסשן הבא
בטעינה מחדש, Claude Code שומר את החיבורים החיים של שרתי תוספים שההגדרה שלהם לא השתנתה, ועושה אותו דבר כשמחליפים את רשימת שרתי ה-MCP של הסשן מ-Agent SDK בלי לנקוב בשמם
כשמעבירים את הסשן עם /cd ב-v2.1.246 ואילך, Claude Code מחבר את השרתים של תוספים שההגדרות של הספרייה החדשה מפעילות, ומנתק את השרתים של תוספים שכבר לא מופעלים, כך שאין צורך להריץ /reload-plugins אחרי המעבר
בסשנים בענן, קריאת MCP לשרת תוסף שעדיין לא מחובר, למשל מיד אחרי שסשן במנוחה מתעורר, מפעילה את השרת לפי דרישה וממתינה עד שהוא מתחבר
מצייני נתיב: ${CLAUDE_PLUGIN_ROOT} מומר לספריית ההתקנה של התוסף, ${CLAUDE_PLUGIN_DATA} לספריית המצב הקבוע שלו, ו-${CLAUDE_PROJECT_DIR} לשורש הפרויקט היציב. ההחלפה חלה על:
שרתי stdio: command, args, env
שרתי http, sse ו-ws: url, headers ו-headersHelper
גישה למשתני הסביבה של המשתמש: גישה לאותם משתני סביבה כמו בשרתים שהוגדרו ידנית
כמה סוגי תעבורה: תמיכה בתעבורות stdio, SSE, HTTP ו-WebSocket, אם כי תמיכת התעבורה עשויה להשתנות לפי השרת
שרתי תוספים מופיעים ב-/mcp עם סימונים שמראים שהם מגיעים מתוספים.
claude mcp get מסתיר את הערכים שהוגדרו לשרת stdio או WebSocket של תוסף, כי הם יכולים לשאת פרטי גישה:
שרת stdio: הוא מדפיס Command: stdio, שורת Args: ריקה, וכל משתנה סביבה כ-NAME=[REDACTED]
שרת WebSocket: הוא מדפיס URL: ws וכל כותרת כ-<name>: [REDACTED], ו-claude mcp list מציג ws במקום ה-URL
כדי לראות מה התוסף הגדיר, מצאו את התוסף בדיסק וקראו את .mcp.json או plugin.json שלו.
שמות כלי MCP של תוספים:
כלים משרת MCP שצורף לתוסף כוללים גם את שם התוסף וגם את מפתח השרת בשם שאפשר לקרוא לו. הצורה המלאה היא mcp__plugin_<plugin-name>_<server-name>__<tool-name>, וכל תו שמחוץ ל-A-Z, a-z, 0-9, _ ו-- מוחלף ב-_. עבור שרת database-tools שצורף לתוסף בשם my-plugin, כלי query ניתן לקריאה כך:
mcp__plugin_my-plugin_database-tools__query
השתמשו בשם המלא הזה כשמפנים לכלי בכללי הרשאות, ברשימת allowed-tools של skill, בשדה tools של subagent, או בהתאמת hook. התאמת hook שנכתבה מול מפתח השרת החשוף, כמו mcp__database-tools__.*, לעולם לא מופעלת עבור שרת שצורף לתוסף.
השרת עצמו נרשם תחת השם התחום plugin:<plugin-name>:<server-name>, למשל plugin:my-plugin:database-tools. השתמשו בשם הזה במקום שבו צפוי שם של שרת מוגדר, כמו שדה server של hook מסוג mcp_tool.
אפשר להגדיר שרתי MCP בשלושה היקפים. ההיקף שבוחרים קובע באילו פרויקטים השרת נטען, והאם ההגדרה משותפת עם הצוות. מנהלים יכולים גם לפרוס או לספק שרתים לכל משתמש דרך הגדרה מנוהלת.
היקף מקומי הוא ברירת המחדל. שרת בהיקף מקומי נטען רק בפרויקט שבו הוספתם אותו, ונשאר פרטי לכם. Claude Code שומר אותו ב-~/.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. הדוגמה הבאה מראה את התוצאה כשמריצים אותה מ-/path/to/your/project:
שרתים בהיקף פרויקט מאפשרים שיתוף פעולה בצוות על ידי שמירת ההגדרות בקובץ .mcp.json בספריית השורש של הפרויקט. כשמוסיפים שרת בהיקף פרויקט, Claude Code יוצר או מעדכן את הקובץ הזה אוטומטית עם מבנה ההגדרה המתאים. הכניסו את .mcp.json לבקרת גרסאות כדי שכל מי בצוות יקבל את אותם כלי MCP ושירותים.
# Add a project-scoped server
claude mcp add --transport http shared-server --scope project https://example.com/mcp
מסיבות אבטחה, Claude Code מבקש אישור בסשנים אינטראקטיביים לפני שימוש בשרתים בהיקף פרויקט מקובצי .mcp.json. כדי לאפס את בחירות האישור האלה, הריצו claude mcp reset-project-choices.
בהרצות claude -p, בסשנים של Agent SDK, ובסשנים בענן מחוץ לשרשורים של פרויקט, Claude Code לא יכול להציג את הבקשה הזו: הוא טוען שרתים בהיקף פרויקט בלי לשאול. Claude Code גם מדלג על הבקשה בסשן שמתחילים במצב bypassPermissions כש-skipDangerousModePermissionPrompt מוגדר בהגדרות המשתמש או בהגדרות המנוהלות. כדי להשאיר שרת בחוץ בכל זאת:
אל תכללו הגדרות פרויקט לגמרי עם --setting-sources או עם אפשרות settingSources של ה-SDK.
התחילו את הסשן עם --strict-mcp-config. אז Claude Code משתמש רק בשרתי ה-MCP שמעבירים עם --mcp-config. דילוג על בקשת האישור עבור השרתים בהיקף פרויקט ש-Claude Code לא טוען דורש Claude Code v2.1.246 ואילך. לפני v2.1.246, סשן strict עדיין המתין לאישור עבורם, וזה השאיר סשנים ברקע ממתינים בהפעלה. ראו שליטה בלעדית עם managed-mcp.json למה שהדגל עושה תחת קובץ MCP מנוהל.
שרתים בהיקף משתמש נשמרים ב-~/.claude.json ומספקים נגישות בין פרויקטים, כך שהם זמינים בכל הפרויקטים במחשב ונשארים פרטיים לחשבון המשתמש. ההיקף הזה מתאים לשרתי עזר אישיים, לכלי פיתוח, או לשירותים שמשתמשים בהם לעתים קרובות בפרויקטים שונים.
# Add a user server
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic
כשאותו שרת מוגדר ביותר ממקום אחד, Claude Code מתחבר אליו פעם אחת, לפי ההגדרה מהמקור בעדיפות הגבוהה ביותר. נעשה שימוש בכל רשומת השרת מהמקור הזה. שדות לא ממוזגים בין היקפים.
Claude Code מתאים כפילויות בין שלושת ההיקפים לפי שם. הוא מתאים תוספים ומחברים לפי נקודת קצה, כך שאחד שמצביע על אותו URL או אותה פקודה כמו שרת מופעל שמעליו נחשב לכפילות.
שתי כתיבות URL נחשבות לאותה נקודת קצה כשהן נבדלות רק ברישיות האותיות של הסכמה או המארח, ביציאת ברירת המחדל של הסכמה, כמו :443 ב-https, או בלוכסן בסוף. נתיב שונה, מחרוזת שאילתה, userinfo, או יציאה שאינה יציאת ברירת המחדל יוצרים שני שרתים.
שרת שהארגון מספק דרך ההגדרה המנוהלת managedMcpServers מדורג מעל כל אלה, כך שכשאחד מהם מכפיל אותו, Claude Code מתחבר להגדרה של הארגון. נדרש Claude Code v2.1.259 ואילך.
אם פותחים סשן מקומי בלשונית Code של אפליקציית Desktop עם אותו שם שרת stdio ברמה העליונה של ~/.claude.json (היקף משתמש) וב-.mcp.json, לשונית Code משתמשת בהגדרה מ-~/.claude.json.
Claude Code תומך בהרחבת משתני סביבה בקובצי .mcp.json, וכך צוותים יכולים לשתף הגדרות ועדיין לשמור גמישות לנתיבים שתלויים במכונה ולערכים רגישים כמו מפתחות API.
אפשר להפנות למשתנה סביבה בערך command, args, env, url או headers של שרת, באחת משתי צורות:
${VAR}: מתרחב לערך של משתנה הסביבה VAR
${VAR:-default}: מתרחב לערך של VAR אם VAR מוגדר, או ל-default אם הוא לא מוגדר
אם משתנה סביבה שמופנים אליו לא מוגדר ואין לו ערך ברירת מחדל, ההגדרה עדיין נטענת: Claude Code מדווח אזהרה על משתנה חסר עבור השרת הזה בפלט של claude mcp list, ומשתמש בטקסט ${VAR} הלא מורחב כפי שהוא. הגדירו את המשתנה או הוסיפו גיבוי :-default כדי שהשרת יתחיל עם הערך שאליו התכוונתם. ב-url וב-headers של שרת מרוחק, חלק ממשתני פרטי הגישה נקראים כריקים במקום זאת, בלי אזהרה.
אם מגדירים משתנה למחרוזת ריקה, הוא נחשב כמוגדר, כך שהפניה ${VAR:-default} מתרחבת למחרוזת הריקה ולא ל-default. עם שרת הדוגמה, אם מגדירים את API_BASE_URL למחרוזת ריקה, ה-url שלו הופך ל-/mcp ו-claude mcp list מדווח ש-'url' is not a valid URL. כדי להשתמש בברירת המחדל, בטלו את הגדרת המשתנה במקום להגדיר אותו למחרוזת ריקה.
ב-url וב-headers של שרת מרוחק, Claude Code קורא משתני פרטי גישה מהסביבה כריקים במקום להרחיב אותם. זה מונע מקובץ .mcp.json של פרויקט או מתוסף לשלוח את פרטי הגישה של Claude Code או של ספק הענן לשרת שהוא מציין. אם כותבים Bearer ${ANTHROPIC_AUTH_TOKEN}, השרת מקבל Bearer בלי פרטי גישה ודוחה את הבקשה, בדרך כלל עם 401. Claude Code מדווח על זה כחיבור שנכשל.
השמות הכלולים הם:
פרטי הגישה של Claude Code עצמו, כמו 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 של שרת מרוחק מפנים למשתנה כלול שהגדרתם, Claude Code מציין אותו בשורת יומן ניפוי. כדי לקרוא את השורה, הריצו claude --debug-file /tmp/claude-debug.log וחפשו בקובץ הזה את never expanded toward a remote server.
שרת ה-MCP המרוחק של GitHub מאמת באמצעות personal access token של GitHub שמועבר כ-header. כדי לקבל אחד, פתחו את הגדרות הטוקנים של GitHub, צרו fine-grained token חדש עם גישה למאגרים שאתם רוצים ש-Claude יעבוד איתם, ואז הוסיפו את השרת:
החליפו את YOUR_GITHUB_PAT ב-personal access token שלכם. הפקודה claude mcp add שומרת את התצורה בלי לאמת credentials, כך שערך placeholder מתקבל כאן אבל השרת נכשל בחיבור אחר כך. כדי לאמת את החיבור, הריצו /mcp ובדקו ששורת השרת מציגה סימן וי. שרת עם credentials שגויים מציג ✘ במקום, ופירוט הכשל שלו כולל את סטטוס ה-HTTP שהשרת החזיר, למשל 401.
DBHub, החבילה @bytebase/dbhub, הוא שרת MCP שמחבר את Claude למסד נתונים יחסי דרך מחרוזת החיבור שאתם מעבירים ב---dsn. השתמשו במשתמש מסד נתונים לקריאה בלבד במחרוזת החיבור כדי שהשאילתות ש-Claude מריץ לא יוכלו לשנות נתונים:
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
--dsn "postgresql://readonly:[email protected]:5432/analytics"
כדי לוודא שהשרת עולה, הריצו /mcp ובדקו ששורת db מציגה סימן וי.
אחר כך שאלו את מסד הנתונים בשפה טבעית:
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 רבים מבוססי ענן דורשים אימות. Claude Code תומך ב-OAuth 2.0 לחיבורים מאובטחים.
Claude Code מסמן שרת מרוחק כדורש אימות כשהשרת מגיב עם 401 Unauthorized או 403 Forbidden. מה ש-Claude Code מציג תלוי בשרת:
עבור שרת שעדיין לא נכנסתם אליו, כל אחד משני קודי הסטטוס מסמן אותו ב-/mcp כדי שתוכלו להשלים את תהליך ה-OAuth.
עבור מחבר claude.ai, 401 שנגרם מכך ש-claude.ai דחה את session token שלכם לא מסמן את המחבר, כי אישור מחדש של המחבר לא יכול לתקן את ההתחברות. Claude Code מציג במקום זאת את מצב דחיית ה-session token.
עבור שרת שהגדרתם לו header בשם Authorization, ב-headers או דרך headersHelper, 401 או 403 בזמן החיבור לא מסמן את השרת, כי ה-credential שצריך לתקן הוא זה שהגדרתם. Claude Code מדווח על החיבור כנכשל במקום זאת. אם הגדרתם את ה-header הזה מהפניה ${VAR}, בדקו אם המשתנה הזה הוא אחד ש-Claude Code קורא כריק.
עבור מחבר שנמסר לסשן ענן, Claude Code לא מריץ תהליך כניסה, כי ה-proxy של הסשן מאמת מול המחבר עם ההרשאה שהענקתם ב-claude.ai. כשמחבר שם צריך אישור מחדש, חברו אותו מחדש ב-claude.ai/customize/connectors ולא מתוך הסשן.
כששרת OAuth שכבר נכנסתם אליו דוחה את הטוקן השמור שלכם עם 401 Unauthorized, Claude Code מתחבר מחדש עם טוקן חדש או בלי:
לכניסה השמורה שלכם יש refresh token: הוא מרענן את הטוקן, מתחבר מחדש, ומנסה שוב את הבקשה פעם אחת. השרת מסומן ב-/mcp רק אם גם הניסיון החוזר נכשל.
לכניסה השמורה שלכם אין refresh token: הוא מתחבר פעם אחת בלי הטוקן. אם השרת עונה, הכלים שלו עובדים בזמן שאתם מנותקים, והטוקן שנדחה נמחק. אם השרת דוחה גם את החיבור הזה, /mcp מציג שהשרת צריך אימות.
בהרצה של claude -p או Agent SDK ב-macOS, בקשה ש-Claude Code שלח בזמן שלא הצליח לקרוא את הטוקן השמור נכשלת עם שגיאת stored-credentials.
כשהשרת דוחה את ה-refresh token השמור, Claude Code מציג מיד הודעה שמפנה אל /mcp. פתחו את /mcp ובחרו Re-authenticate על השרת כדי להיכנס שוב לפני שקריאת הכלי הבאה נכשלת.
שרת מותאם שמחזיר header בשם WWW-Authenticate שמצביע על שרת ההרשאה שלו מקבל את אותו גילוי אוטומטי כמו כל שרת מרוחק אחר.
Claude Code גם מציג הודעת הפעלה כשאחד או יותר מהשרתים המוגדרים צריכים אימות, כך שאין צורך לפתוח את /mcp כדי לגלות אילו שרתים צריכים כניסה. ההודעה סופרת רק שרתים שאפשר להיכנס אליהם מתוך Claude Code. לפני v2.1.218 היא ספרה גם מחברי claude.ai שלא היו מחוברים ב-claude.ai, ואפשר לחבר אותם רק מהגדרות claude.ai.
ההודעה מכריזה על כל שרת פעם אחת ומוציאה אותו מהספירה בהפעלות מאוחרות יותר עד שהשרת הזה התחבר וצריך כניסה שוב. /mcp עדיין מציג כל שרת שצריך כניסה.
להרצה של claude -p או Agent SDK אין לוח /mcp, ולכן Claude Code לא יכול להריץ שם את תהליך ה-OAuth. כדי להשתמש בשרת שצריך אימות, השלימו את הכניסה קודם מסשן אינטראקטיבי: הריצו /mcp בסשן, או claude mcp login <name> ב-shell. כששרת מוגדר צריך אימות במהלך הרצה של claude -p או Agent SDK עם tool search מופעל, Claude Code אומר ל-Claude שהכלים של השרת לא זמינים עד שתאשרו אותו.
אם הגדרתם headers.Authorization לשרת והשרת דוחה את ה-header הזה, Claude Code מדווח על החיבור כנכשל במקום לחזור ל-OAuth. בדקו שהטוקן תקף לנקודת הקצה של ה-MCP, או הסירו את ה-header כדי להשתמש בתהליך ה-OAuth.
1. הוסיפו את השרת שדורש אימות
אם כבר הוספתם את שרת sentry ב-התחלה המהירה של MCP, דלגו על הצעד הזה: הרצה חוזרת של claude mcp add עם אותו שם שרת באותו scope נכשלת עם MCP server sentry already exists in local config. אחרת, הריצו:
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
2. השתמשו בפקודה /mcp בתוך Claude Code
ב-Claude Code, השתמשו בפקודה:
/mcp
אחר כך עקבו אחרי הצעדים בדפדפן כדי להתחבר.
[!TIP]
טיפים:
טוקני אימות נשמרים בצורה מאובטחת ומתרעננים אוטומטית
השתמשו ב-"Clear authentication" בתפריט /mcp כדי לבטל גישה
אם הדפדפן לא נפתח אוטומטית, העתיקו את כתובת ה-URL שסופקה ופתחו אותה ידנית
אם הפניית הדפדפן נכשלת עם שגיאת חיבור אחרי האימות, הדביקו את כתובת ה-callback המלאה משורת הכתובת של הדפדפן לתוך בקשת ה-URL שמופיעה ב-Claude Code
הפקודה claude mcp login <name> מריצה את תהליך ה-OAuth של שרת מוגדר ישירות מה-shell, כך שאין צורך לפתוח את לוח /mcp בתוך סשן. עבור מחבר claude.ai, עקבו אחרי אישור מחבר מחדש מה-shell.
claude mcp login sentry
כדי לנקות credentials שמורים אחר כך, הריצו claude mcp logout <name>.
claude mcp login מזהה כשאין דפדפן מקומי זמין, למשל במהלך סשן SSH או ב-Linux בלי display server, ומדפיס את כתובת ההרשאה במקום לנסות לפתוח דפדפן. פתחו את הכתובת במחשב המקומי, ואז הדביקו את כתובת ההפניה המלאה משורת הכתובת של הדפדפן בחזרה בבקשה. הפקודה צריכה מסוף אינטראקטיבי לשלב ההדבקה, אז התחברו עם ssh -t. העבירו --no-browser כדי לכפות את בקשת הכתובת גם כשמזוהה דפדפן מקומי.
חלק משרתי MCP דורשים redirect URI מסוים שנרשם מראש. כברירת מחדל, Claude Code בוחר פורט פנוי אקראי ל-callback של OAuth. השתמשו ב---callback-port כדי לקבע את הפורט כך שיתאים ל-redirect URI שנרשם מראש בצורת http://localhost:PORT/callback. אם הכניסה ב-Claude Code v2.1.229 נכשלת עם אי התאמה של redirect URI, ראו את הערת הגרסה תחת שימוש ב-credentials של OAuth שהוגדרו מראש.
אפשר להשתמש ב---callback-port לבד (עם רישום לקוח דינמי) או יחד עם --client-id (עם credentials שהוגדרו מראש).
# Fixed callback port with dynamic client registration
claude mcp add --transport http \
--callback-port 8080 \
my-server https://mcp.example.com/mcp
חלק משרתי MCP לא תומכים בהגדרת OAuth אוטומטית דרך Dynamic Client Registration. אם אתם רואים שגיאה כמו "Incompatible auth server: does not support dynamic client registration", השרת דורש credentials שהוגדרו מראש. Claude Code תומך גם בשרתים שמשתמשים ב-Client ID Metadata Document (CIMD) במקום Dynamic Client Registration, ומגלה אותם אוטומטית. אם הגילוי האוטומטי נכשל, רשמו אפליקציית OAuth דרך פורטל המפתחים של השרת קודם, ואז ספקו את ה-credentials כשמוסיפים את השרת.
1. רשמו אפליקציית OAuth אצל השרת
צרו אפליקציה דרך פורטל המפתחים של השרת ורשמו את ה-client ID ואת ה-client secret.
אם טופס הרישום מבקש redirect URI, בחרו כל פורט פנוי והזינו http://localhost:PORT/callback עם הפורט הזה. תשתמשו באותו פורט בצעד הבא.
ב-v2.1.229, Claude Code שלח http://127.0.0.1:PORT/callback במקום זאת, ושרתים שמתאימים בדיוק את ה-redirect URI הרשום דחו את הכניסה עם אי התאמה של redirect URI. Claude Code v2.1.231 החזיר את צורת localhost. כדי להתאושש ב-v2.1.229, שדרגו את Claude Code, או הוסיפו זמנית את הצורה http://127.0.0.1:PORT/callback ל-redirect URI הרשומים של השרת.
2. הוסיפו את השרת עם ה-credentials שלכם
הלשוניות מכסות את שתי הפקודות: claude mcp add מקבל את ה-client ID ואת פורט ה-callback כדגלים, ו-claude mcp add-json מקבל אותם באובייקט oauth. אם רשמתם redirect URI, הגדירו את פורט ה-callback לפורט שב-URI הזה.
claude mcp add
השתמשו ב---client-id כדי להעביר את ה-client ID של האפליקציה. הדגל --client-secret מבקש את הסוד עם קלט מוסתר:
הריצו /mcp ב-Claude Code ועקבו אחרי תהליך הכניסה בדפדפן.
[!TIP]
טיפים:
ה-client secret נשמר בצורה מאובטחת ב-keychain של המערכת (macOS) או בקובץ credentials, לא בתצורה שלכם
אפשר להגדיר את ה-client secret רק כשמוסיפים את השרת. כשאתם מאמתים עם claude mcp login או מ-/mcp, Claude Code משתמש בסוד השמור ולא מבקש אחד ולא קורא את MCP_CLIENT_SECRET
כדי להוסיף או לשנות את הסוד אחר כך, הסירו את השרת עם claude mcp remove <name>, ואז הוסיפו אותו שוב עם --client-secret ועם אותו --scope
אם השרת משתמש בלקוח OAuth ציבורי בלי סוד, השתמשו רק ב---client-id בלי --client-secret
הדגלים האלה חלים רק על תעבורות HTTP ו-SSE. אין להם השפעה על שרתי stdio
השתמשו ב-claude mcp get <name> כדי לוודא ש-credentials של OAuth מוגדרים לשרת
הפנו את Claude Code לכתובת URL מסוימת של מטא-נתוני שרת הרשאת OAuth כדי לעקוף את שרשרת הגילוי ברירת המחדל. הגדירו authServerMetadataUrl כשנקודות הקצה הסטנדרטיות של שרת ה-MCP מחזירות שגיאה, או כשאתם רוצים לנתב את הגילוי דרך proxy פנימי. כברירת מחדל, Claude Code בודק קודם RFC 9728 Protected Resource Metadata ב-/.well-known/oauth-protected-resource, ואז נופל חזרה למטא-נתוני שרת הרשאה לפי RFC 8414 ב-/.well-known/oauth-authorization-server.
הגדירו oauth.scopes כדי לקבע את ה-scopes ש-Claude Code מבקש במהלך תהליך ההרשאה. זו הדרך הנתמכת להגביל שרת MCP לתת קבוצה שאושרה על ידי צוות האבטחה כששרת ההרשאה ב-upstream מפרסם יותר scopes ממה שאתם רוצים להעניק. הערך הוא מחרוזת אחת מופרדת ברווחים, בהתאם לפורמט פרמטר scope ב-RFC 6749 §3.3.
oauth.scopes מקבל עדיפות גם על authServerMetadataUrl וגם על ה-scopes שהשרת מגלה ב-/.well-known. השאירו אותו לא מוגדר כדי לתת לשרת ה-MCP לקבוע את קבוצת ה-scope המבוקשת.
כש-oauth.scopes לא מוגדר, Claude Code לא מבקש את קטלוג scopes_supported המלא ממטא-נתוני שרת הרשאה שהתגלו אוטומטית. מטא-נתונים שנשלפו מ-authServerMetadataUrl מוגדר עדיין מספקים את scopes_supported שלהם כ-scopes המבוקשים.
אם שרת ההרשאה מפרסם offline_access ב-scopes_supported, Claude Code מוסיף אותו ל-scopes הקבועים כדי שאפשר יהיה לרענן את ה-access token בלי כניסה חדשה בדפדפן.
אם השרת מחזיר אחר כך 403 insufficient_scope לקריאת כלי, הקריאה נכשלת עם הודעת needs additional permissions שמציינת את ה-scope שהשרת מבקש. השרת מוצג כצריך אימות ב-/mcp.
אם ה-scope הזה לא נמצא ב-oauth.scopes הקבוע שלכם, הוסיפו אותו, ואז הריצו /mcp ואמתו את השרת שוב. Claude Code מבקש את ה-scopes הקבועים ולא את ה-scope שהשרת ציין, כך שאם תאמתו שוב בלי להוסיף אותו, לטוקן שתקבלו עדיין חסר אותו.
אם שרת ה-MCP שלכם משתמש ב-OAuth מאחורי proxy או gateway שבודק header משלו, הכניסה נכשלת כשבבקשות ה-OAuth חסר ה-header הזה. כניסה דרך ה-proxy דורשת Claude Code v2.1.299 או מאוחר יותר, עם ה-header והכניסה מוגדרים שניהם:
ה-header של ה-proxy: העבירו אותו עם --header, שדה headers, או headersHelper, תחת השם שה-proxy קורא
כניסת ה-OAuth: השאירו את Authorization מחוץ ל-headers המוגדרים, ואז היכנסו עם claude mcp login <name> ב-shell. אם אתם מגדירים header בשם Authorization, Claude Code משתמש בו כ-credential של השרת ולא חוזר ל-OAuth עבור השרת הזה.
כשאימות כמו Kerberos, אסימונים קצרי חיים, או SSO פנימי צריך כותרות שנוצרות בזמן החיבור, הגדירו את headersHelper של השרת לפקודה. Claude Code מריץ אותה בעת החיבור וממזג את הפלט שלה לתוך הכותרות שהוא שולח. הדוגמה הזו משתמשת בסקריפט:
הפקודה חייבת לכתוב ל-stdout אובייקט JSON של זוגות מפתח וערך מסוג מחרוזת
Claude Code מריץ את הפקודה במעטפת ומוותר עליה אחרי 10 שניות
Claude Code בוחר את ספריית העבודה של הפקודה לפי המקום שבו הגדרתם את השרת, לכן תנו את הסקריפט כנתיב מוחלט או שימו אותו ב-PATH
כותרות דינמיות דורסות כל headers סטטיות עם אותו שם
Claude Code מריץ את העוזר מחדש בכל חיבור, בתחילת סשן ובחיבור מחדש, ברגע שכלל האמון לשרתים בהיקף פרויקט ובהיקף מקומי מאפשר לו לרוץ. הוא לא שומר את התוצאה במטמון, ולכן הסקריפט שלכם אחראי לכל שימוש חוזר באסימון.
אם קריאת כלי מחזירה 401 Unauthorized או 403 Forbidden, Claude Code מריץ מחדש את העוזר באופן אוטומטי לפי אותו כלל, מתחבר מחדש עם הכותרות החדשות, ומנסה את הקריאה פעם אחת נוספת. Claude Code מסמן את השרת כזקוק לאימות ב-/mcp רק אם גם הניסיון הזה נכשל.
כשפלט העוזר כולל כותרת Authorization, Claude Code משתמש באישור הזה כאימות של השרת ולא עובר ל-OAuth עבור השרת.
אם השרת דוחה את האישור של העוזר בזמן החיבור, Claude Code מדווח על החיבור ככושל במקום לסמן את השרת כזקוק לאימות. תקנו את האישור שהעוזר מחזיר, ואז התחברו מחדש מ-/mcp כדי להריץ את העוזר שוב.
Claude Code מגדיר את משתני הסביבה האלה בעת הרצת העוזר:
משתנה
ערך
CLAUDE_CODE_MCP_SERVER_NAME
השם של שרת ה-MCP
CLAUDE_CODE_MCP_SERVER_URL
ה-URL של שרת ה-MCP
CLAUDE_PLUGIN_ROOT
ספריית השורש של התוסף. מוגדר רק כשתוסף מספק את השרת
השתמשו בהם כדי לכתוב סקריפט עוזר אחד שמשרת כמה שרתי MCP.
headersHelper שמסופק על ידי תוסף לא יכול להפנות לערכי ${user_config.*} של התוסף, כי הפקודה רצה דרך מעטפת. Claude Code מדווח שהשרת מוגדר באופן שגוי עם שגיאה ואינו מחליף את הערך. שימו את ${user_config.KEY} בשדה headers של השרת, שאינו מפורש על ידי המעטפת, או שסקריפט העוזר יקרא את הערך מקובץ הגדרות. לפני v2.1.207, headersHelper החליף ערכי ${user_config.*}.
Claude Code בוחר את ספריית העבודה של פקודת headersHelper מתוך ההגדרה שמצהירה על השרת. cd ש-Claude מריץ ב-Bash לא מזיז אותה, ו-/cd מזיז אותה רק עבור שרתים שרצים מספריית העבודה הראשית של הסשן. כל שורה למטה נותנת את הספרייה שנתיב יחסי בפקודת headersHelper שלכם נפתר מולה.
לפני v2.1.238, Claude Code גם הריץ את העוזרים של שרתים בהיקף משתמש, מנוהלים, ומחברי claude.ai, ושל קבצי סוכן מחוץ לפרויקט שלכם, מהספרייה שבה הפעלתם אותו.
headersHelper שמאגר או תוסף מספקים הוא פקודה שלא כתבתם, ולכן Claude Code מריץ אותו בלי משתני האישורים מהסביבה שלכם, כמו ANTHROPIC_API_KEY. המקום שבו הגדרתם את השרת קובע אם זה חל:
מוסרים: שרת בקובץ .mcp.json של פרויקט או בתוסף, ושרת מוטמע בקובץ סוכן מהפרויקט שלכם או מספריית --add-dir
מלבד משתני GIT_CONFIG_KEY_<n> של Git, Claude Code מסיר כל משתנה מהסביבה שלכם ששמו נראה כמו אישור, כמו שם שמכיל TOKEN, SECRET, PASSWORD, KEY, או AUTH בכל מצב אותיות, כך ש-ANTHROPIC_API_KEY ו-MY_REGISTRY_TOKEN שניהם מוסרים. Claude Code גם מסיר רשימה קבועה של משתני אישורים ששמותיהם לא עוקבים אחר התבנית הזו, כמו ANTHROPIC_CUSTOM_HEADERS.
כשזה חל על העוזר שלכם, הסקריפט צריך לקרוא את האישור שלו מקובץ או ממחסן אישורים. אם url של השרת נושא את הערך החי של אחד מהמשתנים האלה, כמו MY_REGISTRY_TOKEN, ערך CLAUDE_CODE_MCP_SERVER_URL שהעוזר מקבל מחליף גם את החלק הזה ב-REDACTED.
Claude Code מריץ headersHelper כפקודת מעטפת שרירותית. עבור שרת בקובץ .mcp.json של פרויקט או בהיקף מקומי, הוא מריץ את העוזר רק אחרי שאתם מקבלים את תיבת הדו-שיח של האמון עבור ספריית הפרויקט שבה השרת מוצהר. לפני v2.1.238, סשן claude -p או SDK הריץ את העוזרים האלה בלי לבדוק אמון, וסשן אינטראקטיבי הריץ אותם אחרי שסמכתם על תיקיית אב.
אמון שלא נחשב: אמון של תיקיית אב, והאמון האוטומטי שסשן claude -p או SDK מקבל עבור הוקים בקבצי הגדרות
עד שתסמכו על התיקייה: Claude Code מחבר את השרת עם headers הסטטיות שלו בלבד. בסשן claude -p או SDK הוא גם מדפיס שורת headersHelper not run אחת לכל שרת ל-stderr, ואומר לכם איך להעניק את האמון.
אמון בלי תיבת דו-שיח: הגדירו את projects["<path>"].hasTrustDialogAccepted ל-true ב-~/.claude.json. <path> הוא התיקייה שכללי היתר של פרויקט ואמון סביבת עבודה אומרים ש-Claude Code ממפתח לפיה את האמון.
Claude Code מחיל את אותו כלל על שרת שמוצהר באופן מוטמע בקובץ סוכן, ובודק מאיפה הגיע קובץ הסוכן: הפרויקט שלכם, עבור קובץ בספריית .claude/agents/ שלו, או ספריית --add-dir. עד שתסמכו על הפרויקט או הספרייה עצמם, Claude Code לא טוען את השרת בכלל, ולכן גם העוזר שלו לא רץ.
התחברות OAuth לשרת MCP נכשלת כששער דורש כותרת, כמו X-API-Key, ו-Claude Code לא שולח אותה. כדי ש-Claude Code ישלח את הכותרת הזו, הוסיפו אותה להגדרת השרת והשתמשו ב-Claude Code v2.1.299 או חדש יותר:
שרת ש-MCP מנוהל או תוסף מספק: בקשו ממנהל המערכת או ממחבר התוסף להוסיף את הכותרת לרשומת השרת
Claude Code מוסיף אז את הכותרות המוגדרות למעט Authorization לבקשות ההתחברות, רענון האסימון, וביטול האסימון שהוא שולח ל-origin של השרת. ה-origin של השרת הוא הסכמה, המארח, והפורט ב-url שלו. שער שדורש את הכותרת עדיין יכול לעצור התחברות בדף ההרשאה או בשרת הרשאה ב-origin אחר:
דף ההרשאה: אתם מתחברים בדף הזה בדפדפן, שלא שולח את הכותרות המוגדרות. אם הדפדפן מקבל את שגיאת השער במקום את הדף, בקשו ממי שמפעיל את השער לאפשר לדף לעבור בלי הכותרת.
שרת הרשאה ב-origin אחר: אם שער מול השרת הזה דורש גם את הכותרת, ההתחברות נכשלת שם. בקשו ממי שמפעיל את השער הזה לאפשר לבקשות OAuth לעבור בלי הכותרת.
אם יש לכם הגדרת JSON לשרת MCP, אתם יכולים להוסיף אותה ישירות:
1. הוספת שרת MCP מ-JSON
# תחביר בסיסי
claude mcp add-json <name> '<json>'
# דוגמה: הוספת שרת HTTP עם הגדרת JSON
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'
# דוגמה: הוספת שרת stdio עם הגדרת JSON
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'
# דוגמה: הוספת שרת HTTP עם פרטי OAuth שהוגדרו מראש
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret
2. אימות שהשרת נוסף
claude mcp get weather-api
[!TIP]
טיפים:
ודאו שה-JSON כולל escaping תקין במעטפת
ה-JSON חייב להתאים לסכמת הגדרת שרת MCP
אפשר להשתמש ב---scope user כדי להוסיף את השרת להגדרת המשתמש שלכם במקום להגדרה הספציפית לפרויקט
אם כבר הגדרתם שרתי MCP ב-Claude Desktop, אתם יכולים לייבא אותם:
1. ייבוא שרתים מ-Claude Desktop
# תחביר בסיסי
claude mcp add-from-claude-desktop
2. בחירת השרתים לייבוא
אחרי הרצת הפקודה תופיע תיבת דו-שיח אינטראקטיבית שמאפשרת לבחור אילו שרתים אתם רוצים לייבא.
3. אימות שהשרתים יובאו
claude mcp list
שמות שרתים שנוספו דרך פקודות claude mcp יכולים להכיל רק אותיות, מספרים, מקפים וקווים תחתונים. Claude Desktop לא מחיל את ההגבלה הזו, ולכן שרת Claude Desktop ששמו מכיל תו אחר, כמו רווח, לא ניתן לייבוא. הייבוא מדווח על כל שם שהוא דוחה ועדיין מייבא את שאר השרתים שבחרתם.
[!TIP]
טיפים:
התכונה הזו עובדת רק ב-macOS וב-Windows Subsystem for Linux (WSL)
היא קוראת את קובץ ההגדרות של Claude Desktop מהמיקום הסטנדרטי שלו בפלטפורמות האלה
השתמשו בדגל --scope user כדי להוסיף שרתים להגדרת המשתמש שלכם
שרתים מיובאים שומרים על אותם שמות כמו ב-Claude Desktop כשהשם מכיל רק אותיות, מספרים, מקפים וקווים תחתונים. Claude Code מדווח על שרת ששמו מכיל תו אחר ומדלג עליו
אם כבר קיימים שרתים עם אותם שמות, הם מקבלים סיומת מספרית (לדוגמה, server_1)
שרתים מ-claude.ai מופיעים ברשימה עם סימנים שמראים שהם מגיעים מ-claude.ai.
Anthropic גם מספקת חלק מה-connectors בעצמה, בלי שאתה או מנהל תוסיפו אותם. בחשבונות שבהם Claude Docs זמין, /mcp מציג claude.ai Claude Docs בלי הגדרה, ו-Claude משתמש בו כשאתה מבקש מסמך שמיועד לאנשים אחרים. כדי לכבות רק את ה-connector הזה, ראה השבתת connectors של claude.ai.
Claude Code מסמן connector כ-managed ב-/mcp ובמנהל /plugin כשהארגון שלך מנהל את האימות שלו ב-claude.ai. סטטוס managed לא משנה את האופן שבו Claude Code מתחבר ל-connector או מחיל את בקרות הכלים של הארגון שלך.
Connectors שמעולם לא התחברת אליהם מכווצים מאחורי שורה Show unused connectors בסוף מקטע claude.ai, כדי שרשימה שהארגון סיפק לא תמלא את הלוח. בחר בשורה כדי להרחיב אותם. Connector שהתחברת אליו בעבר נשאר גלוי גם כשהוא צריך כרגע אימות מחדש.
Connectors מ-claude.ai נטענים רק כששיטת האימות הפעילה שלך היא התחברות במנוי claude.ai. הם לא נטענים, גם אם הרצת בעבר /login, כאשר:
ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, או apiKeyHelper פעיל
ספק צד שלישי כגון Amazon Bedrock או Agent Platform של Google Cloud פעיל
ANTHROPIC_PROFILE, משתני ה-federation, או פרופיל Anthropic פעיל מספקים את האישור
CLAUDE_CODE_OAUTH_TOKEN מחזיק אסימון מ-claude setup-token, שיכול רק לבצע בקשות מודל
אם /mcp לא מציג connector שהוספת, הרץ /status כדי לאשר איזו שיטת אימות פעילה. בטל את משתנה הסביבה הזה, הסר את ההגדרה apiKeyHelper, או כבה את הפרופיל, ואז הרץ /login כדי לבחור את חשבון claude.ai שלך.
אם בעיית רשת זמנית מונעת את טעינת רשימת ה-connectors כשהסשן שלך מתחיל, Claude Code מנסה שוב את הטעינה עד שלוש פעמים ברקע, וה-connectors מופיעים ברגע שניסיון חוזר מצליח. אם הם עדיין לא הופיעו, הפעל מחדש את Claude Code כדי לטעון את הרשימה שוב.
אם /mcp מציג connector כ-session token rejected, או שתצוגת הפרטים שלו מציגה claude.ai rejected the session token, claude.ai דחה את האסימון מההתחברות שלך ל-Claude Code. אישור ה-connector שוב לא מנקה את המצב הזה, כי האישור של ה-connector עצמו ב-claude.ai הוא לא מה שנדחה. כדי לנקות אותו:
הרץ /login כדי להתחבר שוב.
חבר מחדש את ה-connector מ-/mcp.
לפני v2.1.222, Claude Code סימן connectors ככאלה שדורשים אימות במקום זאת, ואישור שלהם לא פתר את זה.
שרת שהוספת ב-Claude Code מקבל עדיפות על פני connector של claude.ai שמצביע על אותה כתובת URL. כשזה קורה, /mcp מציג את ה-connector כמוסתר ומראה איך להסיר את הכפילות אם אתה מעדיף להשתמש ב-connector.
חלק מה-connectors שמתארחים אצל Anthropic, כגון Microsoft 365, Gmail ו-Google Calendar, לא תומכים ב-OAuth מקומי מ-Claude Code כי ספק הזהות במעלה הזרם מקבל רק את כתובת ה-redirect ש-claude.ai רשם. כששרת שהוספת עם claude mcp add או ב-.mcp.json מצביע על אחד מהמארחים האלה ואתה מתחבר אליו מ-/mcp או עם claude mcp login, Claude Code מציג is Anthropic-hosted and doesn't support local OAuth, ומפנה אותך לחבר את השירות ב-claude.ai/customize/connectors במקום זאת.
אחרי שתסיר את הרשומה שלך עם claude mcp remove <name> ותחבר את השירות ב-claude.ai, ה-connector מופיע ב-Claude Code אוטומטית.
אילו הגדרות חלות על connector של claude.ai תלוי במקום שבו הסשן שלך רץ, כי רק חלק מהסשנים טוענים connectors מ-claude.ai בעצמם. כל שורה למטה מציינת איך connectors מגיעים בסוג אחד של סשן ומה שולט בהם שם. לסשני WSL של אפליקציית שולחן העבודה אין שורה כי connectors עדיין נפרסים אליהם.
disableClaudeAiConnectors, ENABLE_CLAUDEAI_MCP_SERVERS, ו-allowAllClaudeAiMcps פועלים רק על השורה הראשונה, ה-connectors ש-Claude Code טוען בעצמו. שתי השורות האחרות שונות ממנה בדרכים האלה:
סשני ענן: רשומות allowedMcpServers ו-deniedMcpServers שמגיעות לסשן, למשל דרך הגדרות שמנוהלות בשרת, מסננות גם את ה-connectors שנמסרו. ה-proxy של הסשן משכתב את כתובת ה-URL של כל connector, ולכן תבנית serverUrl שנכתבה עבור כתובת ה-URL של ה-connector עצמו לא תואמת אותו. כדי לאפשר connectors שנמסרו לצד allowlist של כתובות URL בסביבה שמאוחסנת אצלך, הוסף את רשומות serverUrl שמופיעות תחת תעבורת connector יוצאת מהרשת שלך. Claude Code משמיט את ה-connectors שנמסרו כשיש managed-mcp.json על המארח שמריץ את הסשן, כגון מארח runner שמאוחסן אצלך, בין אם הגדרת allowAllClaudeAiMcps ובין אם לא.
סשנים מקומיים ו-SSH של אפליקציית שולחן העבודה: אפליקציית שולחן העבודה רושמת את ה-connectors כשרתי type: "sdk" בתוך התהליך, ושום הגדרת MCP או managed-mcp.json לא מגיעים אליהם. משתמש מוציא connector מהסשנים שלו על ידי ניתוק שלו ב-claude.ai/customize/connectors. ארגון חוסם כלים של connector או מכבה לגמרי את Claude Code באפליקציית שולחן העבודה.
הארגון שלך יכול להגדיר בקרות לכל כלי על connectors של claude.ai. Claude Code קורא את ההגדרות האלה בהפעלה ואוכף אותן מקומית, מלבד בסשנים מקומיים ו-SSH של אפליקציית שולחן העבודה. שם, אפליקציית שולחן העבודה מונעת כלים blocked לפני שהיא מוסרת connector, וההגדרה ask לא מגיעה אל Claude Code, ולכן הוא מחיל על הכלים האלה את כללי ההרשאה הרגילים של הסשן במקום לבקש אישור בכל קריאה. בסשנים שבהם Claude Code טוען connectors בעצמו, הרץ /mcp כדי לראות איזו הגדרה חלה על כל כלי ב-connector.
כלי שמוגדר ל-ask: Claude Code מבקש אישור בכל קריאה עם הסיבה Your organization requires approval for this tool. הבקשה מופיעה גם במצבי הרשאהacceptEdits, auto, ו-bypassPermissions. בטרמינל, לבקשה אין אפשרות לזכור את הבחירה שלך. גם כללי Allow שתואמים לכלי לא מדלגים על הבקשה. במצב dontAsk, שלעולם לא מבקש אישור, Claude Code דוחה את הקריאה במקום זאת.
כלי שמוגדר ל-blocked: Claude Code מסנן את הכלי החוצה לפני ש-Claude רואה אותו, כך שהוא אף פעם לא מופיע ברשימת הכלים של Claude. בסשנים שבהם Claude Code טוען connectors בעצמו, רשימת הכלים של /mcp עדיין מציגה את הכלי, מסומן disabled by your organization.
אפליקציית שולחן העבודה וצ'אט claude.ai מחילים את אותה הגדרת blocked, כך שגם שם Claude לא יכול להשתמש בכלי חסום, ואי אפשר למנוע כלי מסשנים של אפליקציית שולחן העבודה תוך שמירה עליו זמין בצ'אט. אפליקציית שולחן העבודה מדלגת על connector שכל הכלים שלו חסומים.
Claude Code מחיל את disableClaudeAiConnectors רק על ה-connectors שהוא טוען בעצמו, לא על ה-connectors שמארח ענן או אפליקציית שולחן העבודה מוסרים. כדי לכבות את ה-connectors שהוא טוען, הגדר את ההגדרה ל-true בכל היקף הגדרות:
{
"disableClaudeAiConnectors": true
}
ההגדרה הזו משתמשת בסמנטיקה של any-source-true: true בכל מקור הגדרות מקבל עדיפות. קובץ פרויקט .claude/settings.json שנשמר במאגר יכול להוציא מאגר מה-connectors ש-Claude Code טוען בעצמו, אבל false ברמת הפרויקט לא יכול להפעיל מחדש connectors ש-true ברמת משתמש או מדיניות השבית. שרתים שמועברים במפורש דרך --mcp-config לא מושפעים.
אפשר גם להגדיר את משתנה הסביבה ENABLE_CLAUDEAI_MCP_SERVERS ל-false, שיש לו את אותה השפעה על סשן המעטפת הנוכחי:
ENABLE_CLAUDEAI_MCP_SERVERS=false claude
כדי לחסום connectors בודדים של claude.ai במקום את כולם, הוסף אותם אל deniedMcpServers לפי שם או לפי תבנית URL. לדוגמה, רשומת serverName של "claude.ai Slack" חוסמת את ה-connector של Slack. אפשר גם להריץ /mcp כדי להפעיל או לכבות כל connector ש-Claude Code טוען, עבור הפרויקט הנוכחי בלבד.
הגדרת נתיב קובץ ההפעלה: השדה command חייב להפנות אל קובץ ההפעלה של Claude Code. אם הפקודה claude לא נמצאת ב-PATH של המערכת שלך, תצטרך לציין את הנתיב המלא אל קובץ ההפעלה.
שדה backgroundOutputPath בתוצאת Bash או PowerShell מ-claude mcp serve אומר שהקריאה השאירה את הפקודה שלה רצה ברקע. פקודה רצה ברקע כשהלקוח שלך מגדיר run_in_background: true על הקריאה. פקודה בחזית יכולה גם לעבור לרקע כשהיא מגיעה ל-timeout שלה.
השדה נמצא בטקסט ה-JSON של התוצאה ומחזיק את הנתיב של קובץ הפלט של הפקודה.
כדי לקרוא את הפלט עד כה: פתח את הקובץ בנתיב הזה מהלקוח שלך, או העבר את הנתיב כ-file_path לכלי Read של השרת
כדי לדעת מתי הפקודה הסתיימה: הוסף echo של מחרוזת קבועה לערך command, כמו ב-npm test; echo DONE. הפקודה הסתיימה ברגע שהמחרוזת הזו מופיעה בקובץ. בלי המחרוזת, שום דבר לא מסמן את הסוף, כי Claude Code לא מוסיף שורת סיום לקובץ ולא מודיע ללקוח שלך.
כדי לקרוא את סוף פלט ארוך: Read עם file_path בלבד מחזיר את העמוד הראשון, או נכשל כשהקובץ חורג ממגבלת הגודל. העבר גם offset ו-limit, וזה עובד בכל גודל קובץ:
קרא ל-Read עם offset ו-limit ששניהם מוגדרים ל-1, וקח את totalLines מהתוצאה
קרא שוב ל-Read עם offset שמוגדר ל-totalLines פחות תשע ו-limit שמוגדר ל-10
חפש את מחרוזת ה-echo שלך בעשר השורות האחרונות, שהקריאה השנייה מחזירה
השדה backgroundOutputPath דורש Claude Code בגרסה v2.1.295 או מאוחרת יותר.
כאשר כלי MCP מייצרים פלטים גדולים, Claude Code עוזר לנהל את השימוש בטוקנים כדי למנוע עומס על הקשר השיחה:
סף אזהרת פלט: Claude Code מציג אזהרה כאשר פלט של כלי MCP כלשהו חורג מ-10,000 טוקנים
מגבלה ניתנת להגדרה: אפשר להתאים את המספר המרבי המותר של טוקני פלט MCP באמצעות משתנה הסביבה MAX_MCP_OUTPUT_TOKENS
מגבלה ברירת מחדל: המקסימום ברירת המחדל הוא 25,000 טוקנים
היקף: משתנה הסביבה חל על כלים שלא מצהירים על מגבלה משלהם. כלים שמגדירים anthropic/maxResultSizeChars משתמשים בערך הזה במקום זאת עבור תוכן טקסט, בלי קשר לערך שאליו מוגדר MAX_MCP_OUTPUT_TOKENS. כלים שמחזירים נתוני תמונה עדיין כפופים ל-MAX_MCP_OUTPUT_TOKENS
מעל המגבלה: כאשר תוצאה מוצלחת בלי תוכן תמונה חורגת ממגבלת הטוקנים, Claude Code שומר אותה לקובץ ומחליף אותה בשיחה בהודעה שמציינת את נתיב הקובץ, כדי ש-Claude יקרא את הקובץ כשהוא זקוק לתוכן. הקובץ נכנס לתיקיית tool-results של הסשן תחת ~/.claude/projects/.
גודל תגובה משרתי HTTP ו-SSE: כאשר תגובה משרת HTTP או SSE עוברת 16 MiB, Claude Code מפסיק לקרוא אותה והבקשה נכשלת. המגבלה חלה אחרי פריסת הדחיסה על גוף תגובת JSON אחד או על אירוע אחד של זרם אירועים. אם אתם מתחזקים את השרת, החזירו פחות נתונים בכל תגובה כדי להישאר מתחת למגבלה, למשל על ידי עימוד תוצאות
גודל הודעה משרתי WebSocket: כאשר שרת WebSocket שולח הודעה אחת מעל 16 MiB, Claude Code סוגר את החיבור, וקריאות שנמצאות בתהליך בשרת הזה נכשלות. אם אתם מתחזקים את השרת, החזירו פחות נתונים בכל הודעה כדי להישאר מתחת למגבלה
קריאה ש-Claude Code העביר למשימת רקע מדווחת על התוצאה שלה דרך התראת המשימה. שתי מגבלות נוספות חלות על קריאה שמושלמת בחזית:
מגבלת תווים לתוצאות טקסט: עבור כלי שלא מצהיר על anthropic/maxResultSizeChars, Claude Code שומר תוצאה מוצלחת בלי תוכן תמונה לקובץ ברגע שהיא ארוכה מ-50,000 תווים, יהיה מספר הטוקנים שלה אשר יהיה. הגדרת MAX_MCP_OUTPUT_TOKENS לא משנה את הסף הזה
תוצאות שגיאה: כאשר כלי מחזיר תוצאה שמסומנת isError: true, Claude מקבל את הטקסט של התוצאה כהודעת השגיאה של הכלי. מטקסט שגיאה ארוך מכ-11,000 תווים נשמרים רק 5,000 התווים הראשונים ו-5,000 התווים האחרונים, עם סמן ביניהם שאומר כמה תווים הוסרו
כדי לשנות את מגבלת הטוקנים, הגדירו את MAX_MCP_OUTPUT_TOKENS במעטפת לפני הפעלת Claude Code:
אם אתם בונים שרת MCP, אפשר לאפשר לכלים בודדים להחזיר תוצאות גדולות מסף ברירת המחדל של שמירה לדיסק, 50,000 תווים, על ידי הגדרת _meta["anthropic/maxResultSizeChars"] ברשומת התגובה tools/list של הכלי. Claude Code מעלה את הסף של הכלי הזה לערך המסומן, עד תקרה קשיחה של 500,000 תווים.
זה שימושי לכלים שמחזירים פלטים גדולים מעצם טבעם אבל נחוצים, כמו סכמות מסד נתונים או עצי קבצים מלאים. בלי הסימון, תוצאות מוצלחות שחורגות מסף ברירת המחדל נשמרות לדיסק ומוחלפות בהפניה לקובץ בשיחה.
{
"name": "get_schema",
"description": "Returns the full database schema",
"_meta": {
"anthropic/maxResultSizeChars": 200000
}
}
הסימון חל באופן עצמאי מ-MAX_MCP_OUTPUT_TOKENS עבור תוכן טקסט, כך שמשתמשים לא צריכים להעלות את משתנה הסביבה עבור כלים שמצהירים עליו. כלים שמחזירים נתוני תמונה עדיין כפופים למגבלת הטוקנים.
כאשר כלי MCP מחזיר תמונת PNG, JPEG, GIF או WebP, Claude רואה את התמונה בתוך השיחה. העותק המוטמע עשוי להיות מוקטן או דחוס כדי להתאים למגבלות גודל התמונה של המודל. Claude Code גם שומר את הבתים המקוריים לקובץ בתיקיית tool-results של הסשן תחת ~/.claude/projects/ ונותן ל-Claude את הנתיב. Claude יכול אחר כך לחתוך, להמיר או לעשות שימוש חוזר בקובץ ברזולוציה המלאה עם כלים כמו Bash.
חלק משרתי MCP מצהירים על סכמת הקלט של כלי כאיחוד JSON Schema, עם anyOf, oneOf או allOf ברמה העליונה של הסכמה. ה-API של Claude לא מקבל את מילות המפתח האלה בשורש הסכמה. הוא כן מקבל קומבינטורים מקוננים בתוך properties, ש-Claude Code שולח בלי שינוי.
כלים עם קומבינטור ברמת השורש נשארים זמינים. לפני שליחת הכלי ל-API, Claude Code משטח את הסכמה לאובייקט יחיד ומוסיף בתחילת התיאור של הכלי משפט שאומר ל-Claude אילו קבוצות פרמטרים שייכות יחד:
allOf: מאפיינים מכל ענף ממוזגים, ורשימת required של כל ענף עדיין חלה
anyOf ו-oneOf: מאפיינים מכל ענף ממוזגים, ורשימת required של כל ענף מתוארת בתיאור הכלי במקום להיאכף על ידי הסכמה
השרת שלכם מקבל את הארגומנטים ש-Claude בחר, לכן המשיכו לאמת את הצירוף בצד השרת.
כאשר Claude Code לא יכול לייצר סכמה שה-API מקבל, או בפריסה שלא מקבלת את התצורה המרוחקת שמאפשרת את השכתוב, הוא מדלג על הכלי האחד הזה, רושם את הסיבה בלוג של השרת, ומשאיר את שאר הכלים של השרת זמינים.
אם לאחד הכלים של שרת ה-MCP שלכם יש סכמת קלט שמפרה אחד משני הכללים שה-API אוכף, Claude Code מחריג את הכלי הזה. שאר הכלים של השרת לא מושפעים. Claude Code בודק את שני הכללים בזמן שהוא טוען את הכלים של השרת:
שמות מאפיינים ברמה העליונה חייבים להיות באורך 1 עד 64 תווים ולהשתמש רק באותיות ובספרות ASCII, ב-_, ב-. וב--
הסכמה חייבת להיות תקינה מול מטא-סכמת JSON Schema טיוטה 2020-12. Claude Code מחיל את הבדיקה הזו על סכמות שלא מצהירות על $schema ועל סכמות שמצהירות על טיוטה 2020-12. סכמה שמצהירה על דיאלקט אחר מדלגת על הבדיקה הזו, אם כי בדיקת שם המאפיין שלמעלה עדיין חלה
כאשר Claude Code מחריג כלי, הוא רושם את הסיבה בלוג של השרת ואומר ל-Claude אילו כלים הוחרגו ולמה, כדי שאפשר יהיה לשאול את Claude למה כלי חסר. אם מתקנים את הסכמה בשרת, הכלי חוזר בפעם הבאה ש-Claude Code טוען את הכלים של השרת.
כאשר שליפת דגלי תכונה כבויה או שהדגלים מעולם לא הגיעו, כמו במכונה מבודדת רשת, כלי שמפר כלל לא מוחרג:
Claude מקבל את הכלי בלי שינוי, והלוג של השרת רושם עבורו input schema would be rejected by the Anthropic API
אם שורה בלוג הדיבוג מכילה the API refused this tool's input schema, היא מציינת כלי שהסכמה שלו נדחתה על ידי ה-API בבקשה. Claude Code שולח מחדש את הבקשה הזו כשהכלי מוצהר בלי פרמטרים.
אם אתם משתמשים בשרת: אין צורך לעשות דבר. Claude עדיין יכול לקרוא לכלי, אבל לא רואה את הפרמטרים שלו
אם אתם מתחזקים את השרת: תקנו את סכמת הקלט של הכלי בשרת. שורת הלוג מסתיימת ב-The API said: ובסיבה של ה-API לדחיית הסכמה. אמתו את הארגומנטים שהשרת מקבל, כי Claude קורא לכלי בלי לראות את הפרמטרים שלו
אם /mcp מציג כלי ש-Claude לא יכול לקרוא לו, בדקו אם השם המלא של הכלי ארוך מ-128 תווים. הריצו /mcp בסשן ובחרו את הכלי כדי לראות את השם המלא שלו, כמו mcp__<server>__<tool>. Claude Code משאיר כלי MCP מחוץ לכלים שהוא שולח ל-Claude כאשר השם המלא שלו מעל 128 תווים. ה-API של Claude דוחה בקשה שכוללת כלי כזה, ולכן השארת הכלי בחוץ שומרת על פעילות שאר הכלים של השרת.
אם אתם בונים שרת MCP, אפשר לסמן כלי כדורש אישור מפורש בכל קריאה על ידי הגדרת _meta["anthropic/requiresUserInteraction"] ל-true ברשומת התגובה tools/list של הכלי. הערך חייב להיות הבוליאני של JSON true. כל ערך אחר מתעלמים ממנו.
Claude Code מציג את בקשת ההרשאה של הכלי הזה בכל קריאה, גם ב-acceptEdits, ב-auto וב-bypassPermissions מבין מצבי ההרשאה, ולא מציע עבורו אפשרות "don't ask again". כללי Allow שתואמים לכלי גם הם לא מדלגים על הבקשה. במצב dontAsk, שלעולם לא מציג בקשה, Claude Code דוחה את הקריאה.
הבקשה חייבת להגיע לאדם. במצב לא אינטראקטיבי עם --permission-prompt-tool, תוצאת allow מכלי הבקשה עבור כלי מסומן מומרת ל-deny עם ההודעה MCP tool requires user interaction; not supported via --permission-prompt-tool. ה-canUseTool callback של Agent SDK כן מקבל את הקריאות האלה ויכול לאשר אותן, כי יישום ה-SDK שלכם אמור להציג אותן למשתמש.
השתמשו בזה לכלים שבקשת ההרשאה שלהם היא עצמה המטרה, כמו שלב הסכמה או הענקת גישה שבו אישור אוטומטי היה אומר שאף אדם מעולם לא הסכים. כלים אחרים מאותו שרת שומרים על התנהגות ההרשאה הרגילה שלהם.
רשומת tools/list הבאה מסמנת כלי אחד כדורש אישור תמיד.
{
"name": "grant_access",
"description": "Requests access to a protected resource",
"_meta": {
"anthropic/requiresUserInteraction": true
}
}
חלק מהמשטחים, כמו Remote Control ויישומים שנבנו על Agent SDK, בדרך כלל מאפשרים לאשר קריאות כלים בהקשה אחת. עבור כלי שמסומן בסימון הזה, Claude Code מונע את פעולת ההקשה האחת ומציג את בקשת ההרשאה המלאה של הכלי, כך שהאישור עדיין מגיע מאדם שעונה לבקשה ולא מהקשה.
Claude Code מונע אישור בהקשה אחת באותו אופן לכל בקשת הרשאה שרק תיבת הדו-שיח של הטרמינל יכולה להציג במלואה, כמו בקשה שנושאת אזהרת בטיחות או אפשרות always-allow שהמשטח המרוחק לא יכול להציג. עונים לבקשה הזו בתיבת הדו-שיח של הטרמינל ולא מ-Remote Control.
אם בונים שרת MCP, סמנו את הכלים שבטוח לקרוא להם פעמיים כדי ש-Claude Code יוכל לחזור על קריאה שהייתה ממתינה כשחיבור נסגר. Claude Code יכול לחזור על קריאה כזו לשרת HTTP או למחבר claude.ai פעם אחת, על חיבור חדש. קריאה ש-Claude Code לא חוזר עליה יכולה להיכשל עם connection closed before the tool call was answered.
כדי לסמן כלי, הגדירו אחד מ-annotations האלה ל-true ברשומת tools/list שלו:
idempotentHint: הכלי יכול לשנות משהו, וקריאה חוזרת אליו עם אותם ארגומנטים בטוחה
readOnlyHint: הכלי לא משנה דבר. Claude Code גם מריץ את הקריאות של הכלי במקביל לקריאות אחרות לקריאה בלבד.
לדוגמה, השדות האלה ברשומת tools/list מסמנים את הכלי set_issue_status כבטוח לחזרה:
שרתי MCP יכולים לבקש מכם קלט מובנה באמצע משימה באמצעות elicitation. כאשר שרת צריך מידע שהוא לא יכול להשיג בעצמו, Claude Code מציג תיבת דו-שיח אינטראקטיבית בטרמינל ומעביר את התשובה שלכם בחזרה לשרת. לא נדרשת הגדרה מצדכם: תיבות דו-שיח של elicitation מופיעות אוטומטית כאשר שרת מבקש אותן.
שרתים יכולים לבקש קלט בשתי דרכים:
מצב טופס: Claude Code מציג תיבת דו-שיח עם שדות טופס שהוגדרו על ידי השרת (לדוגמה, בקשת שם משתמש וסיסמה). מלאו את השדות ושלחו.
מצב URL: Claude Code שואל אם לפתוח קישור בדפדפן. שרתים משתמשים במצב הזה לתהליך שמסתיים מחוץ לטרמינל, כמו התחברות.
במצב URL, Claude Code מעביר את ה-URL כארגומנט שורת פקודה למטפל ה-URL של המערכת, ומגביל את האורך של הארגומנט הזה. כאשר ה-URL, לאחר escaping עבור שורת הפקודה, מעל התקרה הזו, אפשר רק לדחות את הבקשה. כל תו שצריך escaping, כמו % או &, נספר ארבע פעמים לקראת התקרה: התו עצמו ועוד שלושה תווי escape. URL בלי אף אחד מהם מגיע לתקרה בכ-8,000 תווים. URL שבנוי ברובו מ-percent-escapes, שבו כל תו שלישי הוא %, מגיע אליה בערך ב-4,000.
כדי להגיב אוטומטית לבקשות elicitation בלי להציג תיבת דו-שיח, השתמשו ב-Elicitation hook.
אם אתם בונים שרת MCP שמשתמש ב-elicitation, ראו את מפרט ה-elicitation של MCP לפרטי הפרוטוקול ולדוגמאות סכמה.
כאשר המשימה של Claude בסשן הענן שלכם ממתינה לבקשה של שרת MCP, השרת צריך משהו מכם, כמו ערך או התחברות. אם הבקשה מופיעה ככרטיס ב-claude.ai/code או בלשונית Code של אפליקציית Desktop, ענו על הכרטיס:
מצב טופס: מלאו את השדות, ואז לחצו Submit
מצב URL: לחצו Open link, סיימו את התהליך שהוא פותח, ואז לחצו I’m done, continue על הכרטיס
כדי לסרב לבקשה, לחצו Decline. Claude ממשיך ברגע שהשרת מגיב.
אם לא רואים כרטיס באף אחד מהמקומות, אי אפשר לענות לבקשה שם. בסשן שלכם, לחצו על כפתור העצירה שם כדי לסיים את התור.
אם בונים שרת MCP, יכולות הלקוח ש-Claude Code שולח כשהוא מתחבר אומרות לשרת אילו מצבי elicitation הוא יכול לבקש. Claude Code מצהיר על elicitation: {form: {}, url: {}} בחיבורים הבאים, כך ששרת על כל אחד מהם יכול לבקש את שני המצבים:
חיבורים בגרסאות הפרוטוקול המוקדמות יותר, 2025-11-25 וישנות יותר, לשרתי stdio, sse, http ו-ws בתצורת MCP של Claude Code של משתמש. דורש Claude Code v2.1.287 או חדש יותר
בשאר החיבורים שלו בגרסאות המוקדמות יותר, כמו למחברי claude.ai, Claude Code מצהיר על elicitation: {} החשוף, שמתיר בקשות elicitation במצב טופס בלבד.
הקלידו @ בהנחיה כדי לראות משאבים זמינים מכל שרתי 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
[!TIP]
טיפים:
משאבים נשלפים אוטומטית ונכללים כקבצים מצורפים כשמפנים אליהם
נתיבי משאבים ניתנים לחיפוש מעורפל בהשלמה האוטומטית של אזכור @
Claude Code מספק אוטומטית כלים להצגת רשימה ולקריאה של משאבי MCP כשהשרתים תומכים בהם
משאבים יכולים להכיל כל סוג תוכן ששרת MCP מספק (טקסט, JSON, נתונים מובנים וכו')
משאבי ממשק של MCP Apps הם רשומות עם URI מסוג ui:// או סוג המדיה text/html;profile=mcp-app: דפים שהיישום המארח מרנדר, ולא תוכן ש Claude קורא. הם לא מופיעים בהצעות @ ולא בתוצאות של כלי רשימת המשאבים, ושרת שמציע רק משאבי ממשק מציג רשימת משאבים ריקה. קריאה של משאב ממשק לפי ה URI שלו עדיין עובדת.
חיפוש כלים שומר על שימוש נמוך בהקשר של MCP על ידי דחיית הגדרות הכלים עד ש Claude צריך אותן. רק שמות הכלים והוראות השרת נטענים בתחילת הסשן, ולכן הוספת שרתי MCP נוספים משפיעה מעט על חלון ההקשר. Claude Code לא קובע תקרת כלים קבועה לכל שרת. הגבול המעשי הוא תקציב חלון ההקשר שלכם.
[!NOTE]
חיפוש כלים לא נתמך בפריסות Microsoft Foundry שמתארחות ב Azure, שדוחות אותו בצד השרת: Claude Code מזהה את הדחייה וטוען את כלי MCP מראש עבור הפריסה הזו. ENABLE_TOOL_SEARCH לא יכול לעקוף את זה, כי הדחייה מגיעה מהפריסה עצמה.
אם אתם בונים שרת MCP, שדה הוראות השרת נעשה שימושי יותר כשחיפוש כלים מופעל. הוראות השרת עוזרות ל Claude להבין מתי לחפש את הכלים שלכם, בדומה לאופן שבו skills עובדים.
הוסיפו הוראות שרת ברורות ותיאוריות שמסבירות:
באיזו קטגוריה של משימות הכלים שלכם מטפלים
מתי Claude צריך לחפש את הכלים שלכם
יכולות מרכזיות שהשרת שלכם מספק
Claude Code חותך תיאור כלי או הוראות שרת שעוברים את מגבלות ברירת המחדל האלה, ו Claude רואה רק את הטקסט שלפני החיתוך:
הוראות שרת, ותיאור של כלי שנטען מראש: 4,096 תווים
התיאור של כלי ש Claude טוען דרך חיפוש כלים: 16,384 תווים
שמרו על תיאורים והוראות תמציתיים, ושימו פרטים קריטיים קרוב להתחלה. כשחיפוש כלים מתאים את השאילתה של Claude לתיאור של כלי, הוא קורא רק את החלק שבתוך המגבלה הקצרה יותר, ולכן שימו גם את המילים ש Claude יחפש קרוב להתחלה. כלי נטען מראש ושומר על המגבלה הקצרה יותר בכל פעם שהוא לא דחוי, למשל כשחיפוש כלים כבוי, כשהכלי מסומן לטעינה מראש, או כשהשרת שלו פטור מדחייה.
לפני v2.1.296, המגבלה הקצרה יותר הייתה 2,048 תווים, ולפני v2.1.295 היא חלה על כל תיאור כלי, כולל תיאור שנטען דרך חיפוש כלים.
כדי לשנות את מגבלות ברירת המחדל של 4,096 ושל 16,384 תווים עבור שרתי MCP בסשן שלכם, הגדירו את CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH למספר תווים. Claude Code משתמש במספר הזה עבור שתי המגבלות. עם 8192, למשל, אתם מעלים את מגבלת 4,096 התווים על הוראות שרת ותיאורי כלים שנטענים מראש, ומורידים את מגבלת 16,384 התווים על תיאורי כלים שנטענים דרך חיפוש כלים. המשתנה הזה דורש את Claude Code v2.1.280 או חדש יותר.
תיאורים והוראות מחלק משרתי MCP ש Anthropic מארחת ב api.anthropic.com מגיעים ל Claude במלואם, והגדרת המשתנה הזה לא חותכת אותם.
כדי לשלוט באופן שבו אחד הכלים של השרת שלכם נטען, הגדירו "anthropic/alwaysLoad" באובייקט _meta של הכלי. מי שמוסיף את השרת שלכם ל Claude Code יכול גם להגדיר alwaysLoad עבור כל השרת בתצורה שלו, וההגדרה שלו יכולה לעקוף את שלכם:
ערך הכלי שלכם
מה קורה
true
הכלי נטען מראש. ההפעלה לא ממתינה לשרת שלכם בגלל הערך הזה. מי שמגדיר את השרת שלכם עדיין יכול לדחות את כל הכלים שלו
false
הכלי נשאר דחוי כשהתצורה שלהם מגדירה "alwaysLoad": true. זה חל כשהשרת שלכם מועבר עם --mcp-config, מסופק על ידי יישום Agent SDK, או מסופק על ידי תוסף. בשרתים אחרים הכלי נטען מראש. דורש את Claude Code v2.1.285 או חדש יותר
רשומת tools/list הבאה מבקשת שכלי אחד ייטען מראש:
{
"name": "search_tickets",
"description": "Searches the ticket tracker by keyword",
"_meta": {
"anthropic/alwaysLoad": true
}
}
חיפוש כלים מופעל כברירת מחדל: כלי MCP דחויים ומתגלים לפי דרישה.
הגדרת CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS משאירה את חיפוש הכלים כבוי. אי אפשר לעקוף את זה על ידי הגדרת ENABLE_TOOL_SEARCH בעצמכם. ב Claude Code v2.1.227 או חדש יותר, הארגון שלכם יכול להשאיר את חיפוש הכלים מופעל תחת המשתנה הזה דרך הגדרות מנוהלות. בסשן שמקבל את תצורת HIPAA, חיפוש הכלים כבוי, ולא ENABLE_TOOL_SEARCH ולא הגדרות מנוהלות מפעילים אותו מחדש. השבתת יכולות טרום פרסום מכסה היכן העקיפה חלה ומה המשתנה מסיר.
Claude Code משתמש בחיפוש כלים ב Claude Opus 4, Claude Sonnet 4, Claude Haiku 4.5, ובמודלים מאוחרים יותר, או ב Opus 4.5, Sonnet 4.5, Haiku 4.5, ובמודלים מאוחרים יותר ב Agent Platform של Google Cloud. במודלים מוקדמים יותר, Claude Code טוען את כל כלי MCP מראש, ו ENABLE_TOOL_SEARCH=true לא עוקף את זה.
ב Agent Platform של Google Cloud, Claude Code מחליט לפי דור המודל:
Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, ומאוחר יותר: חיפוש כלים מופעל כברירת מחדל, כמו ב API של Anthropic.
מודלי Agent Platform מוקדמים יותר: Claude Code טוען את כל כלי MCP מראש, כי שכבות ההגשה שלהם דוחות את כותרת ה beta הנדרשת. ENABLE_TOOL_SEARCH=true לא עוקף את זה.
לפני v2.1.221, Claude Code השבית חיפוש כלים לכל המודלים ב Agent Platform של Google Cloud, אלא אם הגדרתם ENABLE_TOOL_SEARCH=true.
שליטה בהתנהגות חיפוש הכלים נעשית באמצעות משתנה הסביבה ENABLE_TOOL_SEARCH:
ערך
התנהגות
(לא מוגדר)
כל כלי MCP דחויים ונטענים לפי דרישה. נטענים מראש במודלים מוקדמים מ Opus 4 ומ Sonnet 4, במודלי Agent Platform המוקדמים, ובפריסות Microsoft Foundry שמתארחות ב Azure
true
כלי MCP דחויים, עם אותם מצבי גיבוי כמו (לא מוגדר)
auto
מצב סף. כלים שהיו נדחים אחרת נטענים מראש כל עוד ההגדרות שלהם מסתכמות בפחות מ 10% מחלון ההקשר. ב 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
אם אתם דוחים את ToolSearch או משאירים אותו מחוץ ל--tools, כלי MCP נטענים מראש, אבל בקשה עדיין יכולה לשאת רשומת ממלא מקום defer_loading. אם שער דוחה את הרשומה הזו, ראו חיפוש כלים דרך שער LLM.
כש ANTHROPIC_BASE_URL מצביע על שער, Claude Code מצפה שהשער יעביר שדות כלי defer_loading ובלוקים tool_referenceיחד עם הכותרת anthropic-beta. חיפוש כלים מופעל כברירת מחדל מאחורי השער, ולכן כלי MCP דחויים והבקשות כוללות את השדות והבלוקים האלה. לפני v2.1.304, חיפוש כלים היה כבוי מאחורי שער, אלא אם ENABLE_TOOL_SEARCH היה true, auto, או auto:N.
ב v2.1.305 או חדש יותר, Claude Code יכול לנסות שוב בקשה בלי חיפוש כלים אחרי 400 או 422. כשהניסיון החוזר מצליח, שום דבר לא מוצג על המסך ואין צורך לעשות דבר: כלי MCP נטענים מראש. Claude Code מנסה חיפוש כלים שוב מאוחר יותר, במחיר של בקשה נוספת שנדחית.
#כלים שנשארים דחויים מתחת לסף ENABLE_TOOL_SEARCH=auto
אם /context מסמן כלים כ (deferred) או (loaded on-demand) אף על פי שההגדרות שלהם מסתכמות מתחת לסף auto, חיפוש הכלים כבר היה מופעל בשיחה הזו ונשאר מופעל. הסכום יכול לרדת אחר כך, למשל בזמן ששרתי MCP מתחברים מחדש אחרי שאתם ממשיכים סשן. אין צורך לעשות דבר: Claude טוען כל אחד מהכלים האלה כשמשימה צריכה אותו.
אם הכלים של שרת צריכים תמיד להיות גלויים ל Claude בלי שלב חיפוש, הגדירו alwaysLoad ל true בתצורה של השרת הזה. כלי השרת נטענים אז להקשר בלי קשר להגדרת ENABLE_TOOL_SEARCH. השתמשו בזה למספר קטן של כלים ש Claude צריך בכל תור, כי כל כלי שנטען מראש צורך הקשר שהיה זמין אחרת לשיחה שלכם.
רשומת .mcp.json הבאה פוטרת שרת HTTP אחד ומשאירה שרתים אחרים דחויים:
הגדרת alwaysLoad: true גם גורמת להפעלה להמתין לכלי השרת, עם תקרה של פסק זמן החיבור הסטנדרטי של 5 שניות, כי הם חייבים להיות נוכחים כשההנחיה הראשונה נבנית. שרת מרוחק עם רשומת cached תקינה מספק את הכלים שלו מהמטמון בלי להתחבר, ולכן הוא לא מעכב את ההפעלה. שרתים אחרים מתחברים ברקע כברירת מחדל. הגדירו MCP_CONNECTION_NONBLOCKING=0 כדי שגם להם ההפעלה תמתין.
כדי להשאיר את כל הכלים של שרת מאחורי חיפוש כלים, הגדירו "alwaysLoad": false ברשומת השרת הזה בתצורת MCP שלכם. זה כולל כלים שמחבר השרת סימן לטעינה מראש. אם משמיטים את alwaysLoad, הכלים המסומנים האלה נטענים מראש. דורש את Claude Code v2.1.287 או חדש יותר.
שרתי MCP יכולים לחשוף prompts שהופכים זמינים כפקודות ב Claude Code.
prompts משרת בשם anthropic-skills לא מופיעים, כי Claude Code שומר את השם הזה ל skills שמסונכרנים מ claude.ai. הכלים של השרת עדיין עובדים. שנו את שם השרת בתצורת MCP שלכם כדי להציג את ה prompts שלו.
הקלידו / כדי לראות את הפקודות הזמינות לכם, כולל אלה משרתי MCP. Claude Code מציג כל prompt של MCP כ /servername:promptname (MCP). הקלדת /mcp__servername__promptname גם מריצה אותו.
2. הרצת prompt בלי ארגומנטים
/mcp__github__list_prs
3. הרצת prompt עם ארגומנטים
prompts רבים מקבלים ארגומנטים. העבירו אותם מופרדים ברווח אחרי הפקודה. Claude Code מפצל את הארגומנטים לפי רווח לבן, ולכן כל ארגומנט הוא טוקן יחיד:
/mcp__github__pr_review 456
/mcp__jira__create_issue login-bug high
[!TIP]
טיפים:
prompts של MCP מתגלים דינמית משרתים מחוברים
ארגומנטים מנותחים לפי הפרמטרים המוגדרים של ה prompt
תוצאות ה prompt מוזרקות ישירות לשיחה
בצורה /mcp__servername__promptname, Claude Code מחליף כל תו בשם השרת שמחוץ ל A-Z, a-z, 0-9, _ ו - ב _, ומשתמש בשם ה prompt כפי שהשרת מצהיר עליו
לארגונים שצריכים שליטה מרכזית על שרתי MCP שמשתמשים יכולים להתחבר אליהם, ראו תצורת MCP מנוהלת. זה מכסה פריסה של קבוצת שרתים קבועה עם managed-mcp.json, אספקת שרתים לכל משתמש עם managedMcpServers, הגבלת שרתים עם allowedMcpServers ו deniedMcpServers, ומה המשתמשים רואים כששרת חסום.