🔌 פרק 9

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

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

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

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

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

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

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

#חיבור ראשון

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

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

1. הוסיפו את השרת מהמסוף, לא מתוך סשן claude:

   העתק

   claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

   claude mcp add רושם שרת. --transport http אומר שהשרת מתארח בכתובת ולא רץ כתהליך מקומי. claude-code-docs הוא שם שאתם בוחרים. שם אחר, למשל docs, עובד אותו דבר. קלוד קוד משתמש בשם כדי לסמן את הכלים בפלט וכדי להפנות לשרת בפקודות כמו claude mcp remove. https://code.claude.com/docs/mcp היא כתובת השרת.

   הפקודה מדפיסה שורת Added ..., למשל Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config, ואחריה שורת File modified: עם קובץ התצורה שנכתב. שורת Added אומרת שהתצורה נכתבה. local config אומר שהשרת רשום עבורכם בפרויקט הזה. בפרויקט אחר הוא אינו פעיל. רישום אחד לכל הפרויקטים מתואר בסעיף שינוי היקף.

2. בדקו את החיבור:

   העתק

   claude mcp list

   עבור claude-code-docs צפוי ✔ Connected.

   סטטוס	משמעות
   ✔ Connected	מוכן לשימוש. זה מה שצפוי ל-claude-code-docs
   ! Needs authentication	השרת נגיש אבל צריך כניסה בדפדפן, או טוקן עם --header
   ✘ Failed to connect	השרת לא ענה
   ✘ Connection error	ניסיון החיבור זרק שגיאה
   ⏸ Pending approval (run claude to approve)	שרת בהיקף פרויקט שעדיין לא אישרתם
   ⊘ Disabled for this project (re-enable via /mcp)	שרת שכובה לפרויקט ברשימת disabledMcpServers
   ✘ Blocked by enterprise managed policy	מדיניות של הארגון חוסמת את השרת, וקלוד קוד לא יתחבר. שאלו את המנהל איזו מדיניות

   במסופי Windows ישנים, כמו מסוף ברירת המחדל ב-Windows 10, הגליפים האלה אינם נתמכים ומופיעים √ ו-× במקום ✔ ו-✘.

   סטטוס ✘ Rejected ופירוט נוסף נמצאים בסעיף מצבי שרתים.

3. הפעילו סשן ובקשו להשתמש בשרת בשמו:

   העתק

   claude

   העתק

   Use the claude-code-docs server to look up what MCP_TIMEOUT does

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

4. הסרה היא אופציונלית:

   העתק

   claude mcp remove claude-code-docs

   הפקודה מאשרת עם Removed MCP server "claude-code-docs" from local config ושורה File modified: של הקובץ שעודכן. כל שרת מחובר תופס מקום בחלון ההקשר, כי שמות הכלים והוראות השרת נטענים בכל סשן. הסרת שרתים שאין בהם שימוש משחררת את המקום.

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

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

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

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

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

1. התקנת התוסף: בתוסף VS Code או באפליקציית שולחן העבודה, עקבו אחרי התקנת תוסף במקום הצעד הזה. במסוף, הפעילו את קלוד קוד עם claude, ואז הזינו בשורת הפקודה שלו:

   העתק

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

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

   • Marketplace "claude-plugins-official" not found: הוסיפו את שוק התוספים עם /plugin marketplace add anthropics/claude-plugins-official, ואז נסו שוב.
   • Plugin "<name>" not found in marketplace "claude-plugins-official": ייתכן שהעותק המקומי של קטלוג השוק אינו מעודכן. רעננו עם /plugin marketplace update claude-plugins-official, ואז נסו שוב. אם הניסיון החוזר מדפיס את אותה הודעה, ראו בתיעוד הרשמי את Plugin not found in marketplace.

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

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

   העתק

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

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

#התקנת שרתי MCP

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

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

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

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

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

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

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

רשומת JSON שמכילה url ללא type היא שגיאת תצורה, מכיוון שקלוד קוד קורא רשומה ללא type כשרת stdio. קלוד קוד מדלג על השרת ומדווח: MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry.

רק יישום מארח SDK, כגון יישום Agent SDK או אפליקציית שולחן העבודה, יכול לרשום שרת "type": "sdk" שרץ בתוך התהליך. קלוד קוד מדלג על רשומת "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, קלוד קוד מדווח גם על רשומת --mcp-config שדולגה בשדה mcp_server_errors של אירוע system/init, כך שסקריפטים יכולים לזהות שהשרת לא נטען מעולם.

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

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

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

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

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

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

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

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

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

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

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

משתנה זה מוגדר בסביבת השרת ולא בסביבה של קלוד קוד עצמו, ולכן הפניה אליו באמצעות הרחבת ${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, הסימן -- מפריד בין האפשרויות של קלוד קוד עצמו, כגון --transport, --env ו---scope, לבין הפקודה והארגומנטים שמריצים את השרת. כל מה שמופיע אחרי -- מועבר לשרת ללא שינוי.

לדוגמה:

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

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

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

#איך קלוד קוד עוצר שרת stdio

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

• ב-macOS וב-Linux: קלוד קוד שולח SIGINT, ואז SIGTERM אם התהליך עדיין רץ 100 מילישניות אחר כך, ואז SIGKILL אחרי 400 מילישניות נוספות.
• ב-Windows: קלוד קוד סוגר את stdin של השרת, ואז מסיים את עץ התהליכים אם התהליך עדיין רץ 300 מילישניות אחר כך.

לפני גרסה v2.1.296, קלוד קוד ב-Windows סיים את עץ התהליכים מיד, בלי לסגור קודם את stdin ובלי להמתין.

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

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

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

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

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

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

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

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

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

#מכתובת URL

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

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

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

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

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

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

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

#מבלוק JSON של mcpServers

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

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

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

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

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

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

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

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

#ניהול השרתים שלכם

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

# הצגת כל השרתים המוגדרים
claude mcp list

# קבלת פרטים עבור שרת ספציפי
claude mcp get notion

# הסרת שרת
claude mcp remove notion

# (בתוך קלוד קוד) בדיקת סטטוס השרת
/mcp

כאשר מסירים שרת מרוחק, קלוד קוד מוחק גם את טוקני ה-OAuth ורישום הלקוח שנשמרו עבור שרת זה. קלוד קוד אינו מבטל את הטוקנים בשרת ההרשאה שהנפיק אותם. כדי לבטל אותם כששרת ההרשאה תומך בביטול, הריצו claude mcp logout <name> במעטפת לפני claude mcp remove <name>.

אם אותו שם קיים ביותר מהיקף אחד, claude mcp remove מדווח exists in multiple scopes. העבירו --scope כדי לבחור איזה עותק למחוק, למשל claude mcp remove claude-code-docs --scope local.

claude mcp get <name> מראה גם באיזה היקף שמורה הגדרת השרת.

#מצבי שרתים

הפקודה claude mcp add מאשרת הוספה מוצלחת בהדפסת שורת Added ..., כלומר התצורה נכתבה. אם במקום זאת מופיעה הודעת was not saved, או הודעת may not have been saved, התיעוד הרשמי מפנה כל הודעה לרשומת שגיאה נפרדת: MCP server was not saved or removed, ו-MCP server may not have been saved or removed.

הפקודה claude mcp list מציגה סטטוס בריאות לצד כל שרת ברשימה, כגון ✔ Connected, ! Needs authentication או ✘ Failed to connect. סטטוס כשל מעיד שקלוד קוד לא הצליח להתחבר לאותו שרת, ולא שפקודת הרשימה נכשלה.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#זמינות כלים

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

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

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

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

אחרי שממשיכים סשן, קלוד יכול לקרוא לכלי מהשיחה השמורה בזמן ששרת ה-MCP של הכלי עדיין מתחבר. כל עוד השרת בניסיון החיבור הראשון, קלוד קוד מחזיק את הקריאה עד 10 שניות ומריץ אותה ברגע שהכלי זמין. אם השרת לא מתחבר בזמן, או שהוא כבר מנסה שוב אחרי ניסיון שנכשל, הקריאה נכשלת בשגיאת הכלי No such tool available.

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

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

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

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

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

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

#לקוח MCP: גרסה v1 וגרסה v2

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

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

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

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

ב-v2 קלוד קוד גם:

• שואל שרתי HTTP, שרתי stdio ושרתי מחברי claude.ai אם הם תומכים בגרסה החדשה, ומשתמש בה מול מי שתומך. זה כולל את המחברים של סשני ענן ושל Remote Control. לכל שאר השרתים הוא מתחבר כמו ב-v1.
• מקבל התראות list_changed משרתים על הגרסה החדשה, דרך זרם שהוא מחזיק פתוח.
• אינו רושם כערוץ שרת channel שמתחבר על הגרסה החדשה, כי הגרסה הזו אינה נושאת הודעות ערוץ.
• נכשל בכניסת OAuth של MCP אם תשובת ההרשאה מציינת מנפיק (issuer) לא צפוי.
• שולח פרטי OAuth של MCP רק לנקודת token שמוגשת ב-HTTPS, או ב-localhost, ב-127.0.0.1 או ב-::1. כניסה נכשלת כשנקודת ה-token היא http:// בכל מקום אחר, למשל מכשיר ברשת המקומית. ראו את השגיאה Refusing to send credentials to non-https token endpoint.

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

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

#עדכון רשימת הכלים בלי ניתוק

שרת MCP יכול לשנות כלים, פרומפטים או משאבים בזמן שהוא מחובר, ולשלוח התראת list_changed. כשהתראה מגיעה:

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

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

#זרם התראות ב-v2

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

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

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

#חיבור מחדש כששרת נופל

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

#נפילה באמצע הסשן

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

• בסשן אינטראקטיבי: /mcp מציג את השרת כממתין בזמן הניסיונות. אחרי חמישה כישלונות קלוד קוד מסמן את השרת כנכשל, או כזקוק לאימות כשהשרת צריך הרשאה מחדש. בסימון כנכשל מופיעה ההודעה MCP server "<name>" disconnected · open /mcp to reconnect. אפשר לנסות ידנית מ-/mcp.
• בהרצות claude -p ובסשני Agent SDK: אותם חמישה ניסיונות, בלי לוח /mcp שמציג אותם. אם כל החמישה נכשלים, ההרצה ממשיכה בלי הכלים של השרת:
  • אחרי שגיאה חולפת, כמו תשובת 5xx או timeout: קלוד קוד ממשיך לנסות שרת HTTP או SSE ברקע. הניסיונות נמשכים עד כחצי שעה, והכלים חוזרים להיות זמינים כשניסיון מצליח להתחבר. עד אז סשן Agent SDK מדווח על הסטטוס failed, והקוד שלכם יכול לחבר את השרת מחדש. כדי לחבר מחדש ב-claude -p, התחילו את ההרצה מחדש.
  • כשהשרת צריך שתיכנסו שוב: קלוד קוד מפסיק לנסות, וסשן Agent SDK מדווח על הסטטוס needs-auth. היכנסו עם claude mcp login <name> במעטפת. אחר כך התחילו את ההרצה מחדש, או בסשן Agent SDK חברו את השרת מחדש.

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

כשחיבור ראשון של שרת HTTP או SSE נכשל בשגיאה חולפת, כמו תשובת 5xx, סירוב חיבור או timeout, קלוד קוד מנסה עד שלוש פעמים. אם החיבור עדיין נכשל, השרת מסומן כנכשל.

קלוד קוד אינו מנסה שוב במקרים האלה:

• חיבור ראשון של שרת stdio. כדי לנסות שוב, ראו את הסעיף הבא.
• חיבור ראשון של שרת WebSocket. בסשן מסוף אינטראקטיבי, כדי לנסות שוב, בחרו Reconnect מתפריט השרת ב-/mcp.
• שגיאת אימות או not-found, כי הפתרון הוא שינוי תצורה. כש-headersHelper הוא המקור היחיד לכותרת Authorization, קלוד קוד כן מנסה שוב שגיאת אימות, כי הוא מריץ את ה-helper מחדש בכל ניסיון ויכול לקלוט אישור חדש.

#שרתי stdio שיוצאים או נכשלים בעלייה

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

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

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

#ניסיון חוזר ידני

כדי לנסות שוב כל שרת שנכשל או שזקוק לאימות, הריצו /mcp reconnect all. במסוף אינטראקטיבי זה דורש קלוד קוד מגרסה v2.1.284 ומעלה. בגרסה מוקדמת יותר הפקודה מדפיסה שם MCP server "all" not found.

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

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

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

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

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

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

קלוד קוד שואל שרתי stdio על הגרסה הזו כברירת מחדל. כדי להשאיר שרת ערוץ ב-stdio על לחיצת היד הקודמת, הגדירו MCP_PROTOCOL_NEGOTIATION ל-legacy. הערך legacy משאיר כל שרת על לחיצת היד הקודמת.

[!TIP] דגלים קצרים וזמני עלייה:

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

#מגבלת זמן לקריאת כלי והעברה לרקע

כדי להגביל כמה זמן קריאת כלי יכולה לרוץ:

• לשרת אחד: שדה timeout ברשומת השרת, במילישניות.
• לכל השרתים: MCP_TOOL_TIMEOUT.

שדה timeout ברשומת השרת ב-.mcp.json הוא תקרת שעון קיר לכל קריאת כלי, ומדרס את MCP_TOOL_TIMEOUT לאותו שרת בלבד. התראות התקדמות מהשרת אינן מאריכות אותו. לדוגמה, "timeout": 600000 הוא עשר דקות. ערך מתחת ל-1000 מתעלמים ממנו, והקריאה נופלת ל-MCP_TOOL_TIMEOUT, או לברירת המחדל של כ-28 שעות כשהמשתנה אינו מוגדר.

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

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

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

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

הזמנים האלה תוחמים כמה זמן קריאה יכולה לרוץ, ולא תמיד כמה זמן היא חוסמת את הסשן. קריאה בשיחה הראשית שעדיין רצה אחרי שתי דקות עוברת למשימת רקע. אם תצוגת הפרטים של קריאה ברקע ב-/tasks מציגה runs on the server; survives exiting this session, זו משימת MCP שרצה על השרת, בסעיף משימות MCP.

זמן עליית שרת נקבע במשתנה MCP_TIMEOUT, במילישניות. בפתרון התקלות, ברירת המחדל שמופיעה שם היא 30 שניות, למשל MCP_TIMEOUT=60000 claude. ב-PowerShell:

$env:MCP_TIMEOUT = "60000"; claude

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

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

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

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

קריאות שנשארות בחזית:

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

אפשר לאמת מול שרת מרוחק שדורש OAuth 2.0 באמצעות /mcp.

#משימות MCP שרצות על השרת

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

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

[!NOTE] משימות MCP הן בטא ציבורית ב-CLI של קלוד קוד, ודורשות קלוד קוד מגרסה v2.1.304 ומעלה. מה נדרש כדי שקריאה תהפוך למשימה מתואר למטה.

#לעצור משימה או לקבל את התוצאה

כדי לעצור משימה רצה, בחרו אותה ב-/tasks והקישו x, או בקשו מקלוד. קלוד קוד מפסיק לעקוב ומבקש מהשרת לבטל, אם כי השרת עדיין יכול לסיים. קודם חברו מחדש שרת מנותק מ-/mcp, אחרת לא יוצאת בקשת ביטול, וקלוד קוד שוכח את המשימה ואינו יכול לעקוב אחריה שוב. Esc אינו עוצר משימת רקע.

כשהמשימה נגמרת, בתמליל מופיעה שורה כמו:

MCP task <server task id> (<server>/<tool>) completed.

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

#תשובה לשאלה ממשימת MCP

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

בסשן לא אינטראקטיבי, קלוד קוד מבקש מהשרת לבטל משימה שמבקשת קלט, בלי להריץ hooks בשם Elicitation ובלי לקרוא ל-callback onElicitation של Agent SDK.

#יציאה, ניקוי או המשך בזמן שמשימה רצה

משימה על שרת מרוחק ממשיכה אחרי היציאה. תהליך של שרת stdio נעצר כשקלוד קוד יוצא, אף על פי שהמשימות שלו מציגות ב-/tasks את runs on the server; survives exiting this session. אלא אם תיעוד השרת אומר שהעבודה חיה אחרי התהליך, תנו למשימות להסתיים או עצרו אותן ב-/tasks קודם.

#מה צריך כדי שקריאה תהפוך למשימת MCP

קריאת כלי הופכת למשימת MCP רק כשכל התנאים האלה מתקיימים:

• השרת תומך במשימות.
• השרת הוא HTTP, stdio, או מחבר claude.ai, מחובר על גרסת הפרוטוקול 2026-07-28. MCP_SDK_GENERATION=v1 או MCP_PROTOCOL_NEGOTIATION=legacy מוציאים את זה.
• הסשן מושך דגלי יכולת, ולכן לא אצל ספק צד שלישי כמו Amazon Bedrock, ולא כשטלמטריה או משיכת דגלים כבויות.
• Anthropic הפעילה משימות MCP לסוג הסשן. בגרסה v2.1.304 ומעלה זה מכסה סשני CLI במסוף, סשני Agent SDK, והרצות GitHub Actions. משטחים אחרים, כמו תוסף VS Code ואפליקציית שולחן העבודה, אינם מקבלים משימות MCP.
• הקריאה באה מהשיחה הראשית, לא מסוכן משנה.
• או שהסשן אינטראקטיבי, או שסשן Agent SDK או הרצת claude -p שקוראת --input-format stream-json עומדים בכל אלה:
  • CLAUDE_AUTO_BACKGROUND_TASKS הוא 1
  • CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND אינו 1
  • CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS אינו 0

כל קריאה אחרת היא קריאת כלי רגילה, והסעיף על העברה אוטומטית לרקע אומר אילו מהן עוברות לרקע.

השאירו את הקלט של סשן Agent SDK או stream-json פתוח, כי אחרי סגירת הקלט ההרצה אינה ממתינה למשימות MCP. הרצת claude -p "<prompt>" חד-פעמית אינה מקבלת משימות MCP.

#הודעות סטטוס על משימת MCP

ההודעות האלה, ברשומת /tasks או בשורת הסיום בתמליל, אומרות שקלוד קוד אינו מגיע לשרת או למשימה. כל עוד אחת מהן מוצגת ב-/tasks, ייתכן שהעבודה עדיין רצה: קלוד קוד משאיר אותה וממשיך לבדוק. הודעות 300s והודעות התצורה נשארות על הרשומה גם אחרי שהקשר חוזר.

#מגבלות זמן על משימות MCP

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

#לגרום לקלוד להמתין לתוצאה

בסשן אינטראקטיבי, הגדירו אחד משני משתני סביבה, למשל בבלוק env של settings.json:

• CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS שווה ל-0: קלוד ממתין לכל קריאת כלי MCP עד שהקריאה נגמרת.
• CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND שווה ל-1: קלוד ממתין לתוצאת המשימה. כשההעברה האוטומטית לרקע פעילה, הקריאה עוברת אחרי שתי דקות כברירת מחדל, כך שמשימות קצרות מסתיימות במקום ומשימות ארוכות אינן חוסמות. הקריאה שעברה היא קריאת רקע רגילה, לא משימת MCP. היא אינה שורדת יציאה מהסשן.

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

הגדרת CLAUDE_CODE_DISABLE_BACKGROUND_TASKS ל-1, או התחלה ב-bare mode, לבד אינן גורמות לקלוד להמתין למשימות MCP. הדוגמה הזו קובעת CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS ל-0, כך שקלוד ממתין לכל קריאת כלי MCP:

{
  "env": {
    "CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS": "0"
  }
}

#משימות MCP למי שבונה שרת

אם אתם בונים שרת MCP, אפשר לענות לקריאת tools/call ארוכה במשימה. הרחבת המשימות של MCP מגדירה את ההודעות. בחיבור על גרסת פרוטוקול 2026-07-28, כל בקשה נושאת את יכולות הלקוח של קלוד קוד ב-params._meta["io.modelcontextprotocol/clientCapabilities"], עם "io.modelcontextprotocol/tasks": {} תחת extensions. בקשת tools/call שאינה יכולה להפוך למשימה משמיטה את ההרחבה הזו.

ענו במשימה רק כשהבקשה נושאת את ההרחבה, אחרת קלוד מקבל את שגיאת הכלי Unsupported result type 'task' for tools/call. אותה שגיאה מופיעה כשחסרים taskId, status, createdAt, lastUpdatedAt או ttlMs. אובייקט המשימה הוא ה-result של JSON-RPC בתשובת tools/call, בלי מערך content. כאן כלולים גם השדות האופציונליים statusMessage ו-pollIntervalMs:

{
  "resultType": "task",
  "taskId": "build-7f3a9c2e",
  "status": "working",
  "statusMessage": "Compiling, 40 of 212 files done",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:03:07Z",
  "ttlMs": null,
  "pollIntervalMs": 5000
}

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

מיד אחרי תשובת המשימה, קלוד קוד שולח tasks/get עם { "taskId": ... }, ואז חוזר על זה פעם בכל מרווח סקר. הרחבת המשימות דורשת שהתשובה תישא "resultType": "complete" יחד עם taskId, status, createdAt, lastUpdatedAt ו-ttlMs. ttlMs יכול להיות null, ו-statusMessage ו-pollIntervalMs אופציונליים. הדוגמה מדווחת שהבנייה הסתיימה:

{
  "resultType": "complete",
  "taskId": "build-7f3a9c2e",
  "status": "completed",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:09:41Z",
  "ttlMs": null,
  "result": {
    "content": [{ "type": "text", "text": "Build succeeded: 212 files, 0 warnings" }]
  }
}

#שרתים שמגיעים מתוסף

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

דוגמה בשורש התוסף:

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

או בתוך plugin.json:

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

בעליית הסשן קלוד קוד מחבר את שרתי התוספים הפעילים. שרת תוסף מרוחק (HTTP או SSE) שכבר השתמשתם בו יכול להופיע בסטטוס cached, והחיבור מתבצע בקריאת הכלי הראשונה. כשחיבור של שרת stdio מתוסף נכשל לפני פחות מ-15 דקות, קלוד קוד מדלג על החיבור. הפעלה או כיבוי של תוסף באמצע סשן מחברים או מנתקים את השרתים כשהשינוי חל. בסשן בלי מסוף אינטראקטיבי, /reload-plugins אינו מחבר או מנתק שרתי MCP של תוספים. השינוי חל בסשן הבא. בטעינה מחדש, חיבורים חיים של שרתים שהתצורה שלהם לא השתנתה נשמרים. אותו דבר קורה כשמחליפים את רשימת שרתי ה-MCP של הסשן מ-Agent SDK בלי לנקוב בשמם.

ב-/cd מגרסה v2.1.246 ומעלה, קלוד קוד מחבר שרתים של תוספים שההגדרות של הספרייה החדשה מפעילות, ומנתק שרתים של תוספים שכבר אינם פעילים, בלי צורך להריץ /reload-plugins אחרי המעבר. בסשן ענן, קריאה לשרת תוסף שעדיין אינו מחובר, למשל אחרי שסשן רדום מתעורר, מפעילה את השרת לפי דרישה וממתינה לחיבור.

מצייני הנתיב: ${CLAUDE_PLUGIN_ROOT} הוא ספריית ההתקנה, ${CLAUDE_PLUGIN_DATA} הוא ספריית המצב הקבוע, ו-${CLAUDE_PROJECT_DIR} הוא שורש הפרויקט היציב. ב-stdio ההחלפה חלה על command, args ו-env. ב-http, sse ו-ws היא חלה על url, headers ו-headersHelper.

claude mcp get מסתיר את הערכים של שרת stdio או WebSocket של תוסף, כי הם יכולים לשאת אישורים:

• שרת stdio: מדפיס Command: stdio, שורת Args: ריקה, וכל משתנה סביבה כ-NAME=[REDACTED].
• שרת WebSocket: מדפיס URL: ws וכל כותרת כ-<name>: [REDACTED]. claude mcp list מציג ws במקום הכתובת.

כדי לראות מה התוסף הגדיר, מצאו את התוסף בדיסק וקראו את .mcp.json או את plugin.json שלו.

שם הכלי הקריא הוא 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 של יכולת, בשדה tools של סוכן משנה, וב-matcher של hook. matcher שנכתב מול מפתח השרת החשוף, כמו mcp__database-tools__.*, אינו נורה לשרת ארוז בתוסף. השרת עצמו נרשם בשם plugin:<plugin-name>:<server-name>, למשל plugin:my-plugin:database-tools. זה השם לשדה server של hook מסוג mcp_tool.

#היקפי התקנה

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

ב-Windows, ~/.claude.json הוא %USERPROFILE%\.claude.json, בדרך כלל C:\Users\YourName\.claude.json. אם הגדרתם CLAUDE_CONFIG_DIR, קלוד קוד קורא את .claude.json מתוך התיקייה הזו.

היקף local הוא ברירת המחדל. השרת נשמר תחת נתיב הפרויקט ב-~/.claude.json ונשאר פרטי. זה מתאים לשרת פיתוח אישי או לשרת עם אישורים שלא אמורים להיכנס ל-git. היקף מקומי של MCP שונה מהגדרות מקומיות כלליות: שרת MCP מקומי נמצא ב-~/.claude.json, והגדרות מקומיות כלליות בקובץ .claude/settings.local.json של הפרויקט.

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

הפקודה כותבת את השרת לרשומת הפרויקט הנוכחי בתוך ~/.claude.json. הרצה מ-/path/to/your/project נראית כך:

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

היקף project כותב או מעדכן את .mcp.json. הכניסו את הקובץ ל-git כדי שכולם יקבלו את אותם כלים.

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

הקובץ שנוצר:

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

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

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

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

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

claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

#שינוי היקף

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

claude mcp remove claude-code-docs --scope local

כדי שהשרת יהיה פעיל בכל הפרויקטים ועדיין פרטי:

claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

כדי לשתף עם הצוות, הוסיפו בהיקף פרויקט. זה כותב ל-.mcp.json בשורש:

claude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp

בצעו commit ל-.mcp.json. מי שמשכפל את המאגר ומפעיל את קלוד קוד רואה בקשה לאשר את השרת, ואז הוא מתחבר גם אצלו.

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

1. היקף מקומי
2. היקף פרויקט
3. היקף משתמש
4. שרתים מתוסף
5. מחברי claude.ai

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

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

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

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

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

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

ההרחבה חלה על command, args, env, url (לשרתי HTTP) ו-headers.

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

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

מחרוזת ריקה נחשבת ערך מוגדר. הפניה ${VAR:-default} מתרחבת אז למחרוזת הריקה, לא ל-default. בשרת הדוגמה, אם API_BASE_URL הוא מחרוזת ריקה, ה-url הופך ל-/mcp ו-claude mcp list מדווח 'url' is not a valid URL. כדי לקבל את ברירת המחדל, בטלו את המשתנה במקום להגדיר אותו למחרוזת ריקה.

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

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

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

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

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

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

לשרת בהיקף מקומי, פרויקט או משתמש, תצוגת הפרטים ב-/mcp וגם claude mcp list ו-claude mcp get מציגים הפניית ${VAR} לפי שם, לא לפי הערך שפוענח. תצוגת /mcp עושה זאת מגרסה v2.1.268 ומעלה. לשרת מ-managedMcpServers המשטחים האלה מציגים רק את המארח של ה-URL.

#דוגמאות חיבור

#GitHub לסקירת קוד

שרת ה-MCP המרוחק של GitHub מאומת עם personal access token של GitHub בכותרת. פתחו את הגדרות הטוקנים ב-GitHub, צרו טוקן fine-grained עם גישה למאגרים שקלוד צריך, ואז הוסיפו את השרת:

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

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

אחר כך אפשר לבקש, למשל: Review PR #456 and suggest improvements, Create a new issue for the bug we just found, Show me all open PRs assigned to me.

שרתים שמאומתים בטוקן סטטי במקום OAuth מקבלים את הטוקן בזמן ההוספה עם --header "Authorization: Bearer <token>", כמו בדוגמה הזו.

#תשאול PostgreSQL

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

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.

#דפדפן מקומי עם Playwright

שרת Playwright MCP נותן לקלוד דפדפן שאפשר לנווט בו, ללחוץ ולקרוא, בלי חשבון. הוא רץ דרך npx ודורש Node.js 18 או חדש יותר. אין דגל --transport, כי שרת מקומי משתמש ב-stdio כברירת מחדל. כל מה שאחרי -- הוא הפקודה שקלוד קוד מריץ, ו--y אומר ל-npx להתקין בלי לשאול:

claude mcp add playwright -- npx -y @playwright/mcp@latest

הפקודה מדפיסה אישור כמו Added stdio MCP server playwright with command: npx -y @playwright/mcp@latest to local config, ואחריה שורת File modified: עם הקובץ שנכתב. שורת Added אומרת שהרשומה נשמרה, לא שהפקודה רצה. Playwright מפעיל את Chrome שכבר מותקן. לדפדפן אחר הוסיפו --browser עם שם הדפדפן אחרי @playwright/mcp@latest, למשל --browser firefox.

1. בדקו עם claude mcp list. הבדיקה הראשונה יכולה להציג ✘ Failed to connect בזמן ש-npx מוריד את החבילה. המתינו והריצו שוב. בסיום ההורדה הסטטוס עובר ל-✔ Connected. אם אחרי כמה ניסיונות עדיין מופיע ✘ Failed to connect, עברו לפתרון התקלות.
2. בקשו משימה שצריכה דפדפן, למשל Use playwright to open https://example.com and tell me the page title. נפתח חלון דפדפן, וקריאות הכלי בפלט מסומנות בשם playwright ובפעולה, כמו browser_navigate.

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

קלוד קוד תומך ב-OAuth 2.0. הוא מסמן שרת מרוחק כזקוק לאימות כשהשרת עונה 401 Unauthorized או 403 Forbidden, לפי השרת:

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

כשבקשה לשרת OAuth שכבר נכנסתם אליו מחזירה 401 Unauthorized, קלוד קוד מתחבר מחדש עם טוקן חדש או בלי טוקן:

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

בהרצת claude -p או Agent SDK ב-macOS, בקשה שקלוד קוד שלח בזמן שלא הצליח לקרוא את הטוקן השמור נכשלת בשגיאת אישורים שמורים.

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

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

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

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

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

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

   העתק

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

   אחרי ההוספה claude mcp list מציג ! Needs authentication. זה צפוי: הצעד הבא משלים את הכניסה. לשירות אחר החליפו את הכתובת, מ-Anthropic Directory או מתיעוד השירות.

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

טוקני האימות נשמרים באופן מאובטח ומתרעננים אוטומטית. Clear authentication בתפריט /mcp מבטל את הגישה. אם הדפדפן אינו נפתח, העתיקו את הכתובת שסופקה. אם ההפניה מהדפדפן נכשלת בשגיאת חיבור אחרי האימות, הדביקו את כתובת ה-callback המלאה משורת הכתובת של הדפדפן אל בקשת ה-URL בקלוד קוד. אימות OAuth עובד עם שרתי HTTP. אחר כך אפשר לשאול משהו שדורש את השירות, כמו What Sentry projects do I have access to?, ולחפש בפלט קריאות כלי שמסומנות ב-sentry.

claude mcp login <name> מריץ את זרימת ה-OAuth מהמעטפת. למחבר claude.ai עקבו אחרי האישור מחדש מהמעטפת בתיעוד Remote Control. claude mcp logout <name> מוחק אישורים שמורים.

claude mcp login sentry
claude mcp login sentry --no-browser

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

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

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

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

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

2. הוסיפו את השרת עם האישורים. --client-secret מבקש את הסוד בקלט מוסתר. ב-add-json שדה oauth נושא את clientId ואת callbackPort, ו---client-secret נשאר דגל נפרד. כדי לקבוע רק פורט callback בלי client ID, מספיק oauth.callbackPort. ב-CI אפשר להגדיר MCP_CLIENT_SECRET כדי לדלג על הבקשה האינטראקטיבית.

   העתק

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

   העתק

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

   העתק

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

   העתק

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

3. הריצו /mcp ועקבו אחרי הכניסה בדפדפן.

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

כדי לעקוף את שרשרת הגילוי, הגדירו authServerMetadataUrl באובייקט oauth. כברירת מחדל קלוד קוד בודק קודם RFC 9728 ב-/.well-known/oauth-protected-resource, ואז RFC 8414 ב-/.well-known/oauth-authorization-server. הכתובת חייבת להיות https://. השדה scopes_supported של המטא-דאטה דורס את ההיקפים שהשרת במעלה הזרם מפרסם.

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

oauth.scopes הוא מחרוזת אחת מופרדת ברווחים, בפורמט פרמטר scope של RFC 6749. הוא גובר גם על authServerMetadataUrl וגם על מה שמתגלה ב-/.well-known. כשהשדה אינו מוגדר, קלוד קוד אינו מבקש את כל קטלוג scopes_supported מגילוי אוטומטי. מטא-דאטה מ-authServerMetadataUrl שהוגדר כן מספק את scopes_supported כהיקפים המבוקשים. אם שרת ההרשאה מפרסם offline_access, קלוד קוד מצרף אותו להיקפים הנעולים כדי שאפשר יהיה לרענן בלי כניסה חדשה בדפדפן.

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

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

#כניסת OAuth דרך פרוקסי שמאמת כותרת

אם שרת MCP משתמש ב-OAuth מאחורי פרוקסי או שער שבודק כותרת משלו, הכניסה נכשלת כשבקשות ה-OAuth מגיעות בלי הכותרת. כניסה דרך הפרוקסי דורשת קלוד קוד מגרסה v2.1.299 ומעלה, וגם את הכותרת וגם כניסת OAuth:

• כותרת הפרוקסי: העבירו אותה עם --header, בשדה headers, או דרך headersHelper, בשם שהפרוקסי קורא.
• כניסת OAuth: השאירו את Authorization מחוץ לכותרות המוגדרות, ואז היכנסו עם claude mcp login <name> במעטפת. אם מגדירים כותרת Authorization, קלוד קוד משתמש בה כאישור השרת ואינו נופל חזרה ל-OAuth עבור השרת הזה.

#כותרות דינמיות

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

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

אפשר גם פקודה בשורה:

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

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

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

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

ספריית העבודה של הפקודה נקבעת לפי המקום שהגדיר את השרת. cd שקלוד מריץ ב-Bash אינו מזיז אותה, ו-/cd מזיז אותה רק לשרתים שרצים מספריית העבודה הראשית של הסשן.

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

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

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

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

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

#כניסה לשרת MCP מאחורי שער שדורש כותרת

כניסת OAuth לשרת MCP נכשלת כששער דורש כותרת, כמו X-API-Key, וקלוד קוד אינו שולח אותה. כדי שקלוד קוד ישלח את הכותרת, הוסיפו אותה לתצורת השרת והשתמשו בקלוד קוד מגרסה v2.1.299 ומעלה:

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

קלוד קוד מוסיף אז את הכותרות המוגדרות, מלבד Authorization, לבקשות הכניסה, רענון הטוקן וביטול הטוקן שהוא שולח ל-origin של השרת. ה-origin הוא הסכמה, המארח והפורט ב-url. שער שדורש את הכותרת עדיין יכול לעצור את הכניסה בדף ההרשאה או בשרת הרשאה על origin אחר:

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

#הוספת שרת מ-JSON וייבוא מ-Claude Desktop

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

   העתק

   claude mcp add-json <name> '<json>'

   העתק

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

   העתק

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

   העתק

   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 <name>.

ה-JSON צריך להתאים לסכמת תצורת שרת MCP, ולהיות מבורח במעטפת. --scope user מוסיף להגדרת המשתמש במקום להגדרה הספציפית לפרויקט.

ייבוא מ-Claude Desktop:

1. הריצו claude mcp add-from-claude-desktop.
2. בחרו אילו שרתים לייבא בתיבת הדו-שיח.
3. ודאו עם claude mcp list.

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

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

אפליקציית הצ'אט Claude Desktop נפרדת מקלוד קוד. כדי להעתיק שרתים מ-claude_desktop_config.json אל ה-CLI, הריצו claude mcp add-from-claude-desktop ב-macOS או ב-WSL.

#מחברי claude.ai

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

1. הוסיפו שרתים ב-claude.ai/customize/connectors. בתוכניות Team ו-Enterprise רק מנהלים יכולים להוסיף שרתים.
2. השלימו את האימות הנדרש ב-claude.ai.
3. בתוך קלוד קוד הריצו /mcp. השרתים מופיעים עם סימון שהם מגיעים מ-claude.ai.

Anthropic גם מספקת חלק מהמחברים בעצמה. בחשבונות שבהם Claude Docs זמין, /mcp מציג claude.ai Claude Docs בלי הגדרה, וקלוד משתמש בו כשאתם מבקשים מסמך שמיועד לאנשים אחרים. כדי לכבות רק את המחבר הזה, הוסיפו רשומת serverName של "claude.ai Claude Docs" ל-deniedMcpServers, או השתמשו במתג /mcp.

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

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

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

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

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

אם /mcp מציג מחבר כ-session token rejected, או שתצוגת הפרטים אומרת ש-claude.ai דחה את טוקן הסשן, אישור מחדש של המחבר אינו מנקה את המצב.

1. הריצו /login והיכנסו מחדש.
2. חברו מחדש את המחבר מ-/mcp.

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

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

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

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

disableClaudeAiConnectors, ENABLE_CLAUDEAI_MCP_SERVERS ו-allowAllClaudeAiMcps פועלים רק על המחברים שקלוד קוד מושך בעצמו.

בסשני ענן, רשומות allowedMcpServers ו-deniedMcpServers שמגיעות לסשן מסננות גם מחברים שנמסרו. הפרוקסי משכתב את כתובת כל מחבר, ולכן תבנית serverUrl שנכתבה לכתובת המקורית של המחבר אינה תואמת. כדי לאפשר מחברים שנמסרו לצד רשימת היתר של URL בסביבה באירוח עצמי, הוסיפו את רשומות serverUrl שמפורטות תחת Connector traffic leaves your network. כשקיים managed-mcp.json על המארח שמריץ את הסשן, קלוד קוד משמיט את המחברים שנמסרו, בין אם הגדרתם allowAllClaudeAiMcps ובין אם לא.

בסשנים מקומיים ו-SSH של שולחן העבודה, האפליקציה רושמת את המחברים כשרתי type: "sdk" בתוך התהליך, ושום הגדרת MCP או managed-mcp.json אינם מגיעים אליהם. משתמש מוציא מחבר מהסשנים שלו על ידי ניתוק ב-claude.ai. ארגון חוסם כלים של מחבר, או מכבה את קלוד קוד באפליקציה כולה.

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

• כלי שמוגדר ask: קלוד קוד שואל בכל קריאה עם הסיבה Your organization requires approval for this tool. השאלה מופיעה גם ב-acceptEdits, ב-auto וב-bypassPermissions, ובלי אפשרות לזכור את הבחירה. כללי allow תואמים אינם מדלגים עליה. במצב dontAsk, שאינו שואל, הקריאה נדחית.
• כלי שמוגדר blocked: הכלי מסונן לפני שקלוד רואה אותו. ברשימת הכלים של /mcp הוא עדיין מופיע, מסומן disabled by your organization.

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

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

{
  "disableClaudeAiConnectors": true
}

ENABLE_CLAUDEAI_MCP_SERVERS=false עושה את אותו דבר לסשן המעטפת הנוכחי:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

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

#קלוד קוד כשרת MCP

claude mcp serve

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

ב-Claude Desktop הוסיפו ל-claude_desktop_config.json:

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

שדה command חייב להצביע על קובץ ההפעלה של קלוד קוד. אם claude אינו ב-PATH, מצאו את הנתיב המלא עם which claude והשתמשו בו:

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

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

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

#קריאת פלט של פקודה ברקע כלקוח MCP

שדה backgroundOutputPath בתוצאת Bash או PowerShell מ-claude mcp serve אומר שהקריאה השאירה את הפקודה רצה ברקע. פקודה רצה ברקע כשהלקוח מגדיר run_in_background: true בקריאה. פקודה בחזית יכולה גם לעבור לרקע כשהיא מגיעה ל-timeout שלה.

השדה נמצא בטקסט ה-JSON של התוצאה ומחזיק את נתיב קובץ הפלט של הפקודה.

• כדי לקרוא את הפלט עד עכשיו: פתחו את הקובץ בנתיב הזה מהלקוח, או העבירו את הנתיב כ-file_path לכלי Read של השרת.
• כדי לדעת מתי הפקודה הסתיימה: צרפו echo של מחרוזת קבועה לערך command, למשל npm test; echo DONE. הפקודה הסתיימה ברגע שהמחרוזת מופיעה בקובץ. בלי המחרוזת שום דבר אינו מסמן את הסוף, כי קלוד קוד אינו מוסיף שורת סיום לקובץ ואינו מודיע ללקוח.
• כדי לקרוא את סוף פלט ארוך: Read עם file_path בלבד מחזיר את העמוד הראשון, או נכשל כשהקובץ עובר את מגבלת הגודל. העבירו גם offset ו-limit. זה עובד בכל גודל קובץ:
  1. קראו ל-Read עם offset ו-limit ששניהם 1, וקחו את totalLines מהתוצאה.
  2. קראו ל-Read שוב עם offset ששווה ל-totalLines פחות תשע, ו-limit של 10.
  3. חפשו את מחרוזת ה-echo בעשר השורות האחרונות שהקריאה השנייה מחזירה.

השדה backgroundOutputPath דורש קלוד קוד מגרסה v2.1.295 ומעלה.

#מגבלות פלט, סכמות ואישור כלי

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

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

• לכלי שאינו מצהיר anthropic/maxResultSizeChars, תוצאת טקסט מוצלחת בלי תמונה ארוכה מ-50,000 תווים נשמרת לקובץ, בלי קשר ל-MAX_MCP_OUTPUT_TOKENS.
• כשהתוצאה מסומנת isError: true, קלוד מקבל את הטקסט כהודעת השגיאה. טקסט ארוך מכ-11,000 תווים שומר את 5,000 התווים הראשונים ואת 5,000 האחרונים, עם סמן ביניהם שאומר כמה תווים הוסרו.

קריאת תשובה משרת HTTP או SSE נעצרת אחרי שגוף JSON אחד, או אירוע אחד בזרם אירועים, עובר 16 MiB אחרי פתיחת דחיסה. הבקשה שהתשובה הזו עונה עליה נכשלת. אם אתם מתחזקים את השרת, החזירו פחות נתונים בכל תשובה, למשל עם עימוד.

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

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

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

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

export MAX_MCP_OUTPUT_TOKENS=50000
claude

כשכלי מחזיר תמונת PNG, JPEG, GIF או WebP, קלוד רואה עותק בתוך השיחה, שעשוי להיות מוקטן או דחוס. קלוד קוד שומר גם את הבייטים המקוריים בקובץ תחת tool-results ונותן לקלוד את הנתיב. קלוד יכול אחר כך לחתוך, להמיר או להשתמש מחדש בקובץ ברזולוציה המלאה עם כלים כמו Bash. שמירת תמונות לקובץ דורשת גרסה v2.1.283 ומעלה. עם --no-session-persistence או CLAUDE_CODE_SKIP_PROMPT_HISTORY לא נכתב קובץ תמונה, וקלוד מקבל רק את העותק שבשיחה.

סכמת קלט עם anyOf, oneOf או allOf בשורש אינה מתקבלת ב-API של Claude. ה-API כן מקבל combinators מקוננים בתוך properties, וקלוד קוד שולח אותם בלי שינוי. קלוד קוד משטח סכמה עם combinator בשורש לאובייקט אחד ומוסיף משפט לתיאור הכלי. ב-allOf רשימות required של כל ענף עדיין חלות. ב-anyOf וב-oneOf הרשימות מתוארות בתיאור ואינן נאכפות בסכמה. השרת מקבל את הארגומנטים שקלוד בחר, ולכן כדאי לאמת את הצירוף בצד השרת. אם אי אפשר לייצר סכמה שה-API מקבל, או בפריסה שאינה מקבלת את התצורה המרוחקת שמפעילה את השכתוב, קלוד קוד מדלג על הכלי הזה בלבד, רושם את הסיבה בלוג השרת, ומשאיר את שאר הכלים.

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

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

כשכלי מוצא, קלוד קוד רושם את הסיבה בלוג ואומר לקלוד אילו כלים הוצאו ולמה. אחרי תיקון הסכמה בשרת, הכלי חוזר בטעינה הבאה. ההוצאה מופעלת דרך דגל יכולת. בפריסה שבה משיכת הדגלים כבויה, או במכונה שהדגלים מעולם לא הגיעו אליה, קלוד קוד עדיין מריץ את הבדיקות ורושם בלוג input schema would be rejected by the Anthropic API, אבל שולח את הכלי בלי שינוי. אם ה-API דוחה אחר כך את הסכמה, ראו את הסעיף הבא. לפני גרסה v2.1.216 אף פריסה לא הריצה את הבדיקות. טיפול ב-combinator בשורש נפרד ושומר על ההתנהגות שלו גם כשמשיכת הדגלים כבויה.

#כשה-API מסרב לסכמת הקלט

אם הסשן נכשל בשגיאת 400 שמזהה כלי לפי מיקומו, התיעוד הרשמי מפנה לשגיאה Tool input schema is invalid.

אם שורת לוג דיבוג מכילה the API refused this tool's input schema, היא מציינת כלי שה-API דחה את הסכמה שלו בבקשה. קלוד קוד שולח את הבקשה שוב כשהכלי מוצהר בלי פרמטרים.

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

לפני גרסה v2.1.300, כל תור שכלל את הסכמה שנדחתה נכשל בשגיאת 400 שמזהה את הכלי לפי מיקומו.

#שם כלי ארוך מ-128 תווים

אם /mcp מציג כלי שקלוד אינו יכול לקרוא לו, בדקו אם השם המלא ארוך מ-128 תווים. הריצו /mcp ובחרו בכלי כדי לראות את השם המלא, למשל mcp__<server>__<tool>. קלוד קוד משאיר כלי MCP מחוץ לכלים שהוא שולח לקלוד כשהשם המלא עובר 128 תווים. ה-API של Claude דוחה בקשה שכוללת כלי כזה, ולכן השארת הכלי בחוץ שומרת על שאר הכלים של השרת. ההודעה שמציינת את הכלי, והדרכים לקצר את השם המלא, מתוארות בשגיאה MCP tool name over 128 characters.

כלי עם _meta["anthropic/requiresUserInteraction"] שווה ל-true הבוליאני דורש אישור מפורש בכל קריאה. כל ערך אחר מתעלמים ממנו. האישור נדרש גם ב-acceptEdits, ב-auto וב-bypassPermissions, ובלי אפשרות "אל תשאל שוב". כללי allow אינם מדלגים. במצב dontAsk הקריאה נדחית. שאר הכלים מאותו שרת שומרים על התנהגות ההרשאה הרגילה. מתאים לכלי שהפרומפט עצמו הוא העניין, כמו הסכמה או הענקת גישה, שבה אישור אוטומטי אומר שאף אדם לא הסכים.

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

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

#סימון כלים שאפשר לקרוא להם פעמיים

אם אתם בונים שרת MCP, סמנו כלים שאפשר לקרוא להם פעמיים, כדי שקלוד קוד יוכל לחזור על קריאה שהייתה ממתינה כשחיבור נסגר. קלוד קוד יכול לחזור על קריאה כזו לשרת HTTP או למחבר claude.ai פעם אחת, בחיבור חדש. קריאה שקלוד קוד אינו חוזר עליה יכולה להיכשל עם connection closed before the tool call was answered.

כדי לסמן כלי, הגדירו אחד מהשדות האלה ב-annotations ל-true ברשומת tools/list:

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

לדוגמה, השדות האלה ברשומת tools/list מסמנים את הכלי set_issue_status כבטוח לחזרה:

{
  "name": "set_issue_status",
  "annotations": {
    "idempotentHint": true
  }
}

#בקשות elicitation ומשאבים

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

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

במצב URL הכתובת מועברת כארגומנט למטפל הכתובות של המערכת, עם תקרת אורך אחרי בריחה לשורת הפקודה. כשהכתובת עוברת את התקרה אחרי הבריחה, אפשר רק לדחות את הבקשה. כל תו שדורש בריחה, כמו % או &, נספר ארבע פעמים. כתובת בלי תווים כאלה מגיעה לתקרה בכ-8,000 תווים. כתובת שבנויה בעיקר מ-percent-escapes, שבה כל תו שלישי הוא %, מגיעה אליה בערך ב-4,000. כדי לענות אוטומטית בלי דיאלוג, השתמשו ב-hook בשם Elicitation.

#מענה לבקשת elicitation בסשן ענן

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

• מצב טופס: מלאו את השדות והקישו Submit.
• מצב URL: הקישו Open link, סיימו את הזרימה שנפתחת, ואז הקישו I’m done, continue על הכרטיס.

כדי לסרב לבקשה, הקישו Decline. קלוד ממשיך אחרי שהשרת עונה.

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

#מצבי elicitation שקלוד קוד מצהיר

אם בונים שרת MCP, יכולות הלקוח שקלוד קוד שולח בחיבור אומרות לשרת אילו מצבי elicitation הוא יכול לבקש. קלוד קוד מצהיר elicitation: {form: {}, url: {}} בחיבורים האלה, כך ששרת עליהם יכול לבקש את שני המצבים:

• חיבורים על גרסת פרוטוקול 2026-07-28
• חיבורים על הגרסאות הקודמות, 2025-11-25 ומטה, לשרתי stdio, sse, http ו-ws שבהגדרת MCP של המשתמש. דורש קלוד קוד v2.1.287 ומעלה

בשאר החיבורים על הגרסאות הקודמות, למשל למחברי claude.ai, קלוד קוד מצהיר elicitation: {} בלבד, וזה מתיר בקשות elicitation במצב טופס בלבד.

שרת שנבנה על Java MCP SDK 0.17.0 או מוקדם יותר יכול לסרב להצהרה שיש בה גם form וגם url. התיעוד הרשמי קורא לשגיאה MCP server rejected the elicitation capability.

משאבי MCP מופיעים בהשלמה של @ לצד קבצים. הפניה ספציפית היא @server:protocol://resource/path. אפשר כמה הפניות באותה בקשה. משאב שמוזכר נמשך ומצורף אוטומטית. נתיבים ניתנים לחיפוש מטושטש. קלוד קוד מספק כלים לרשימה ולקריאה כשהשרת תומך בכך. משאב יכול להכיל כל סוג תוכן שהשרת מספק, כמו טקסט, JSON או נתונים מובנים.

Can you analyze @github:issue://123 and suggest a fix?

Please review the API documentation at @docs:file://api/authentication

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

משאבי ממשק של MCP Apps הם רשומות עם URI של ui:// או סוג מדיה text/html;profile=mcp-app. הם אינם מופיעים בהצעות @ או בתוצאות כלי רשימת המשאבים. שרת שמציע רק משאבי ממשק מציג רשימת משאבים ריקה. קריאה לפי ה-URI עדיין עובדת.

#פרומפטים של MCP כפקודות

פרומפטים משרת בשם anthropic-skills אינם מופיעים, כי קלוד קוד שומר את השם ליכולות שמסונכרנות מ-claude.ai. הכלים של השרת עדיין עובדים. שנו את שם השרת בתצורה כדי להציג את הפרומפטים.

1. הקלידו / כדי לראות פקודות, כולל פרומפטים משרתי MCP. כל פרומפט מופיע כ-/servername:promptname (MCP). גם /mcp__servername__promptname מריץ אותו.
2. פרומפט בלי ארגומנטים: /mcp__github__list_prs.
3. פרומפט עם ארגומנטים: הארגומנטים מופרדים ברווח אחרי הפקודה, וכל ארגומנט הוא טוקן אחד, למשל /mcp__github__pr_review 456. גם /mcp__jira__create_issue login-bug high.

בצורה /mcp__servername__promptname, כל תו בשם השרת מחוץ ל-A-Z, a-z, 0-9, _ ו-- מוחלף ב-_, ושם הפרומפט נשאר כפי שהשרת מצהיר עליו. התוצאה מוזרקת ישירות לשיחה.

#עריכת .mcp.json ביד

כל קובץ בטבלת ההיקפים משתמש באותו מבנה JSON לרשומות שרת. הקובץ שכדאי לכתוב ביד הוא .mcp.json, כי הוא נכנס למאגר ומשמש תצורה כקוד לצוות.

צרו .mcp.json בשורש הפרויקט. הדוגמה מגדירה את שרת התיעוד מעל HTTP ואת Playwright כתהליך stdio:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

בשרת HTTP, url הוא נקודת הקצה. בשרת stdio, command ו-args הם התוכנית שרצה.

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

#חיפוש כלים

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

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

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

• הוראות שרת, ותיאור של כלי שנטען מראש: 4,096 תווים.
• תיאור של כלי שקלוד טוען דרך חיפוש כלים: 16,384 תווים.

תיאורים והוראות מחלק משרתי ה-MCP ש-Anthropic מארחת ב-api.anthropic.com מגיעים לקלוד במלואם.

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

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

כדי לשנות את המגבלות לכל שרתי ה-MCP בסשן, הגדירו CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH למספר תווים. המספר מחליף את שתי המגבלות: 8192, למשל, מעלה את הקצרה ומוריד את הארוכה. המשתנה דורש גרסה v2.1.280 ומעלה. הוא אינו משנה את השרתים המארחים ב-api.anthropic.com שהטקסט שלהם מגיע במלואו.

כדי לשלוט בכלי בודד, הגדירו "anthropic/alwaysLoad" ב-_meta של הכלי:

{
  "name": "search_tickets",
  "description": "Searches the ticket tracker by keyword",
  "_meta": {
    "anthropic/alwaysLoad": true
  }
}

ENABLE_TOOL_SEARCH:

חיפוש כלים פעיל כברירת מחדל. כש-ANTHROPIC_BASE_URL מצביע לשער, החיפוש נשאר פעיל: הבקשות כוללות שדות defer_loading ובלוקי tool_reference שהשער אמור להעביר, וכלי ה-MCP נשארים דחויים. כדי לטעון כל כלי מראש הגדירו ENABLE_TOOL_SEARCH=false במעטפת או בשדה env של ההגדרות. לפני גרסה v2.1.304 חיפוש הכלים היה כבוי מאחורי שער, אלא אם ENABLE_TOOL_SEARCH היה true, auto או auto:N.

ENABLE_TOOL_SEARCH=auto:5 claude
ENABLE_TOOL_SEARCH=false claude

אפשר גם לקבוע את הערך בשדה env של settings.json.

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

חיפוש כלים פועל על Claude Opus 4, Claude Sonnet 4, Claude Haiku 4.5, ומודלים מאוחרים יותר, וב-Agent Platform של Google Cloud על Opus 4.5, Sonnet 4.5, Haiku 4.5 ומאוחר יותר. במודלים מוקדמים יותר קלוד קוד טוען את כל כלי ה-MCP מראש, ו-ENABLE_TOOL_SEARCH=true אינו דורס זאת.

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

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

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

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

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

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

השדה alwaysLoad זמין בכל סוגי השרתים.

"alwaysLoad": false משאיר את כל כלי השרת מאחורי החיפוש, כולל כלים שהמחבר סימן לטעינה מראש. זה דורש גרסה v2.1.287 ומעלה. אם משמיטים את השדה, כלים שסומנו כן נטענים מראש.

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

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

#חיפוש כלים דרך שער LLM

מגרסה v2.1.305 ומעלה, קלוד קוד יכול לנסות שוב בקשה בלי חיפוש כלים אחרי תשובת 400 או 422. כשהניסיון מצליח, שום דבר אינו מוצג על המסך ואין צורך לעשות דבר: כלי ה-MCP נטענים מראש. קלוד קוד מנסה חיפוש כלים שוב מאוחר יותר, במחיר של בקשה נוספת שנדחית. כדי לדלג על הבקשות האלה הגדירו ENABLE_TOOL_SEARCH=false.

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS מתואר למעלה. אם בקשה נכשלת בשגיאה שמזכירה defer_loading או tool_reference, התיעוד הרשמי מפנה לשגיאה Extra inputs are not permitted.

#משטחים אחרים

המדריך הזה משתמש בפקודות claude mcp, וכל משטח של קלוד קוד יכול להתחבר לשרתי MCP:

• אפליקציית שולחן העבודה של קלוד קוד: מוסיפים שרתים דרך ממשק Connectors.
• אפליקציית הצ'אט Claude Desktop: אפליקציה נפרדת מקלוד קוד. כדי להעתיק שרתים מ-claude_desktop_config.json אל ה-CLI, הריצו claude mcp add-from-claude-desktop ב-macOS או ב-WSL.
• VS Code: חיבור לכלי MCP חיצוניים מהתוסף.
• סשני ענן: מחוץ לשרשורי פרויקט, בצעו commit ל-.mcp.json. סשן עם מאגר אחד טוען אותו. שרשורי ענן בתוך פרויקט משתמשים במחברי claude.ai.
• claude.ai: מחברים שמוסיפים ב-claude.ai/customize/connectors נטענים ב-CLI כשנכנסים עם החשבון הזה.

#פתרון תקלות

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

#/mcp מציג No MCP servers configured

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

• הרצתם claude mcp add מפרויקט אחר. שרת בהיקף מקומי קשור לפרויקט שבו הוספתם אותו: שורש המאגר, או התיקייה המדויקת אם לא הייתם במאגר git. הוסיפו מחדש מהפרויקט הנוכחי, או עם --scope user כדי שלא יהיה קשור לפרויקט.
• ערכתם קובץ בנתיב הלא נכון. הקבצים הנכונים הם ~/.claude.json ו-<project>/.mcp.json. קלוד קוד אינו קורא נתיבים כמו ~/.claude/.mcp.json, ~/.claude/config/mcp.json, ~/.claude/mcp.json, או %APPDATA%\Claude\mcp.json. להיקף משתמש הריצו claude mcp add --scope user, שכותב למפתח mcpServers ב-~/.claude.json. להיקף פרויקט ערכו את .mcp.json בשורש.
• רשומה פגומה ב-.mcp.json. קלוד קוד מדלג על הרשומה ועדיין טוען את האחרות. הריצו claude mcp list וחפשו אזהרת פענוח, שמציינת את השדה הבעייתי.

#הסטטוס הוא Failed to connect או Connection error

שני הסטטוסים אומרים שהשרת לא עלה או שהכתובת לא ענתה. הם יכולים להופיע גם בשרת HTTP שדוחה טוקן שהגדרתם ב-headers.Authorization. שרת שרוצה טוקן שעדיין לא הגדרתם מציג ! Needs authentication.

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

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

אם שרת HTTP מחזיר 404 Not Found, בחירה בשרת ב-/mcp מציגה MCP endpoint not found at <origin>. Check the URL in your MCP config. ההודעה מציינת את ה-origin, למשל https://mcp.example.com, בלי הנתיב. הריצו claude mcp get <name> כדי לראות את הכתובת המלאה, השוו את הנתיב לנתיב ה-MCP המתועד, ואז claude mcp remove <name> והוסיפו מחדש עם הכתובת הנכונה. לפני גרסה v2.1.219 ההודעה כללה גם את הנתיב. לפני גרסה v2.1.191, תשובת 404 הציגה הודעה כללית Error POSTing to endpoint בלי הכתובת.

לשרת HTTP, בדקו שהכתובת נגישה:

curl -I https://mcp.sentry.dev/mcp

ב-PowerShell השתמשו ב-curl.exe במקום curl, כדי שהבקשה תגיע ל-curl האמיתי ולא לכינוי של Invoke-WebRequest.

• 404 או 405: השרת למעלה. נקודות קצה רבות של MCP עונות רק ל-POST, ועדיין זה מאשר שהכתובת נגישה.
• 401 או 403: השרת למעלה וצריך אימות. השתמשו בכניסה בדפדפן, או בשרת שמקבל טוקן, כמו GitHub, העבירו --header "Authorization: Bearer <token>" ב-claude mcp add.
• אין תשובה: בדקו את הכתובת ואת הרשת.

לשרת stdio, הריצו את הפקודה המוגדרת ישירות במסוף. לשרת Playwright מהמדריך:

npx -y @playwright/mcp@latest

• אם הפקודה עולה וממתינה לקלט, השרת עצמו עובד. הריצו claude mcp get <name> וודאו שהפקודה שם תואמת למה שהרצתם. אם היא שונה, כנראה הושמט -- לפני פקודת השרת. הסירו והוסיפו מחדש עם --. אם כתבתם .mcp.json ביד, בדקו תחביר ומיקום. לפני גרסה v2.1.285, claude mcp get לא הדפיס שורת Command לרשומת stdio שנשמרה בלי שדה type, למשל רשומה שנכתבה ביד. בגרסאות האלה הריצו claude mcp list, שמדפיס את שורת הפקודה בכל מקרה.
• אם הפקודה נכשלת, ההודעה מציינת מה חסר, למשל Node.js או דפדפן.

#timeout בעלייה

השרת חרג מזמן העלייה. ברירת המחדל היא 30 שניות. הרצה ראשונה של שרת stdio יכולה להיות איטית בזמן ש-npx מוריד חבילה. העלו את המגבלה עם MCP_TIMEOUT במילישניות, למשל MCP_TIMEOUT=60000 claude.

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

#השרת כבר קיים

כבר הוספתם שרת בשם הזה באותו היקף. הסירו את הרשומה או בחרו שם אחר:

claude mcp remove claude-code-docs

אם השם קיים ביותר מהיקף אחד, remove מדווח exists in multiple scopes. העבירו --scope, למשל claude mcp remove claude-code-docs --scope local.

#השרת מתחבר אבל אין כלים

הריצו /mcp, בחרו בשרת, וצפו ברשימת הכלים. רשימה ריקה אומרת שהשרת עלה אבל לא רשם כלים, בדרך כלל כי חסר משתנה סביבה כמו מפתח API. העבירו אותו עם --env KEY=value ב-claude mcp add, או בשדה env ברשומה ב-.mcp.json. תיעוד השרת מפרט את המשתנים שהוא צריך.

לפני גרסה v2.1.302, /mcp הציג את הסטטוס tools fetch failed לשרת על גרסת פרוטוקול 2026-07-28 שהשמיט resultType, ttlMs או cacheScope מהתשובות. בגרסאות האלה, אם שרת מציג את הסטטוס, עדכנו את קלוד קוד.

#שינויים ב-.mcp.json אינם נכנסים לתוקף

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

claude mcp reset-project-choices

#כניסת OAuth נכשלת או שהדפדפן אינו נפתח

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

#המשך הגדרה

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