🔌 פרק 9

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

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

ניתן לכתוב שרתי MCP בכל שפה שמסוגלת להדפיס לפלט הסטנדרטי stdout או להגיש נקודת קצה של HTTP, כגון Python, JavaScript, Go ועוד.

התקנה וניהול של שרתי MCP מתבצעים דרך דף Customize בקרסור, או באמצעות קובץ תצורה mcp.json. תוספים רשמיים זמינים ב-Cursor Marketplace, ותוספים ושרתים קהילתיים זמינים במאגר cursor.directory.

#כיצד זה עובד ואופני תקשורת (Transports)

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

קרסור תומך בשלושה אופני תקשורת:

#תמיכה ביכולות הפרוטוקול ובהרחבות (Protocol and Extension Support)

קרסור תומך ביכולות הפרוטוקול ובהרחבות הבאות:

#יישומי MCP (MCP Apps)

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

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

#התקנת שרתי MCP

#התקנה בלחיצה אחת (One-click installation)

ניתן לעיין בתוספים הרשמיים ב-Cursor Marketplace ולהתקין אותם בלחיצה אחת מתוך Customize, או להגדיר שרתים מותאמים אישית באמצעות mcp.json. לשרתים ותוספים מהקהילה, ניתן לעיין ב-cursor.directory. לחיצה על "Add to Cursor" ברשומת Marketplace מתקינה את השרת ומבצעת אימות באמצעות OAuth.

מנהלי צוותים יכולים גם להפיץ שרתי MCP דרך שוק צוותי (team marketplace). שרתים המופצים ברמת הצוות מופיעים ב-Customize לצד שרתי ה-MCP האישיים ושרתי סביבת העבודה.

#הגדרה באמצעות mcp.json

הגדרת שרתי MCP מותאמים אישית מתבצעת בקובץ JSON:

דוגמה לשרת CLI מבוסס Node.js:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

דוגמה לשרת CLI מבוסס Python:

{
  "mcpServers": {
    "server-name": {
      "command": "python",
      "args": ["mcp-server.py"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

דוגמה לשרת מרוחק (שרת MCP הפועל על גבי שרת באמצעות HTTP או SSE):

{
  "mcpServers": {
    "server-name": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "API_KEY": "value"
      }
    }
  }
}

#אימות OAuth סטטי לשרתים מרוחקים (Static OAuth for Remote Servers)

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

• ספק ה-MCP מספק Client ID קבוע (ולעיתים גם Client Secret).
• הספק דורש רישום כתובת URL מאושרת להפניה מחדש (למשל Figma, Linear).
• הספק אינו תומך ברישום לקוחות דינמי לפי OAuth 2.0 (Dynamic Client Registration).

יש להוסיף אובייקט auth לרשומות שרת מרוחק המשתמשות ב-url:

{
  "mcpServers": {
    "oauth-server": {
      "url": "https://api.example.com/mcp",
      "auth": {
        "CLIENT_ID": "your-oauth-client-id",
        "CLIENT_SECRET": "your-client-secret",
        "scopes": ["read", "write"]
      }
    }
  }
}

#כתובות הפניה סטטיות (Static redirect URL)

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

https://www.cursor.com/agents/mcp/oauth/callback
http://localhost:8787/callback

• דפדפן וסוכני Cursor Agents: https://www.cursor.com/agents/mcp/oauth/callback
• אפליקציית שולחן העבודה: http://localhost:8787/callback

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

#שילוב עם אינטרפולציית תצורה

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

{
  "mcpServers": {
    "oauth-server": {
      "url": "https://api.example.com/mcp",
      "auth": {
        "CLIENT_ID": "${env:MCP_CLIENT_ID}",
        "CLIENT_SECRET": "${env:MCP_CLIENT_SECRET}"
      }
    }
  }
}

השתמשו במשתני סביבה עבור Client ID ו-Client Secret במקום להטמיע אותם ישירות בקוד.

#תצורת שרתי STDIO

עבור שרתי STDIO (שרתי שורת פקודה מקומיים), מגדירים את השדות הבאים ב-mcp.json:

האפשרות envFile זמינה אך ורק עבור שרתי STDIO. שרתים מרוחקים (HTTP או SSE) אינם תומכים ב-envFile. עבור שרתים מרוחקים, יש להשתמש באינטרפולציית תצורה עם משתני סביבה המוגדרים בפרופיל המעטפת (shell) או בסביבת מערכת ההפעלה.

#שימוש ב-Extension API

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

רישום שרתים מתבצע באמצעות הפונקציה: vscode.cursor.mcp.registerServer()

#מיקומי קבצי תצורה ואינטרפולציית משתנים

#מיקומי קבצים

• תצורת פרויקט: צרו את הקובץ .cursor/mcp.json בתיקיית הפרויקט עבור כלים ייעודיים לפרויקט זה.
• תצורה גלובלית: צרו את הקובץ ~/.cursor/mcp.json בתיקיית הבית עבור כלים שיהיו זמינים בכל הפרויקטים.

#אינטרפולציית תצורה (Config Interpolation)

ניתן להשתמש במשתנים בתוך ערכי mcp.json. קרסור מפענח משתנים בשדות הבאים: command, args, env, url ו-headers.

תחביר נתמך:

• ${env:NAME}: משתני סביבה
• ${userHome}: נתיב לתיקיית הבית
• ${workspaceFolder}: שורש הפרויקט (התיקייה המכילה את .cursor/mcp.json)
• ${workspaceFolderBasename}: שם תיקיית השורש של הפרויקט
• ${pathSeparator} וכן ${/}: מפריד נתיבי הקבצים של מערכת ההפעלה

דוגמה לשרת מקומי:

{
  "mcpServers": {
    "local-server": {
      "command": "python",
      "args": ["${workspaceFolder}/tools/mcp_server.py"],
      "env": {
        "API_KEY": "${env:API_KEY}"
      }
    }
  }
}

דוגמה לשרת מרוחק:

{
  "mcpServers": {
    "remote-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
      }
    }
  }
}

#אימות (Authentication)

שרתי MCP משתמשים במשתני סביבה לצורך אימות. יש להעביר מפתחות API ואסימונים דרך התצורה. קרסור תומך ב-OAuth עבור שרתים הדורשים זאת.

#בקרות ניהול לארגונים (Enterprise Admin Controls)

הפצת MCP ומדיניות MCP מוגדרות בנפרד. מנהלי צוות (Team admins) יכולים להפיץ שרתי MCP משותפים, ומנהלי ארגון (Enterprise admins) יכולים להגדיר את מדיניות ה-MCP.

#הפצת שרתי MCP לצוות (Team MCP Distribution)

הגדרת שרתי צוות משותפים מתבצעת תחת Dashboard > Plugins & MCPs. שרתים אלה זמינים לסוכני ענן (Cloud Agents).

כדי להפוך שרת צוות קיים ועצמאי לזמין בחלון הסוכן (Agent Window), בעורך (IDE) ובממשק הפקודה (CLI), יש לבחור באפשרות Add to Team Marketplace תחת Team MCP Servers. קרסור יקשר את השרת לשוק ברירת המחדל של הצוות מבלי להפריע לגישת Cloud Agents. חברי הצוות יוכלו להתקין ולהגדיר אותו מתוך Customize.

קישור שרת MCP לשוק אינו מתקין או מפעיל אותו אוטומטית עבור כולם. הגדרת גישה לשוק (Marketplace Access) ומצבי התקנת תוספים מתבצעים תחת Dashboard > Plugins & MCPs.

#רשימת שרתים מאושרים (MCP Allowlist)

מנהלי ארגון יכולים לשלוט באילו שרתי MCP המשתמשים רשאים להריץ דרך לוח הבקרה של קרסור, בנתיב: Team Settings > MCP Configuration (גם דף Plugins & MCPs מקשר לשם). הוספה לרשימת האישורים מהווה אישור לתצורה בלבד, ואינה מפיצה או מתקינה את השרת.

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

• רשומות פקודה (Command entries): מאשרות שרתי stdio מקומיים לפי תבנית פקודה.
• רשומות כתובת (URL entries): מאשרות שרתי HTTP או SSE מרוחקים לפי תבנית כתובת URL.
• רשימות כלים מאושרים (Tool allowlists): מגבילות אילו כלים מתוך שרת מאושר יכולים לרוץ באופן אוטומטי. השארת רשימת הכלים ריקה מאפשרת את כל הכלים של אותו שרת.

#בקרות רשת (Network Controls)

כתובות URL של שרתי MCP מרוחקים מוגבלות לתבנית כתובת ה-URL שהוגדרה.

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

• Allow all: מאפשר גישת רשת יוצאת.
• Allowlist: מאפשר גישה רק ליעדים המופיעים ברשימה.
• Deny all: חוסם גישת רשת יוצאת.
• No sandbox: הרצה ללא ארגז חול לפקודות או לרשת.

#הרחבות MCP של משתמשים (User MCP Extensions)

מנהלים יכולים להתיר למשתמשים להגדיר שרתי MCP משלהם מחוץ לתבניות הפקודה או ה-URL שהוגדרו על ידי המנהל. עבור שרתי משתמש שאינם תואמים לתבנית ניהולית, רשימת חסימת הרשת למשתמשים (User MCP Network Denylist) יכולה לחסום יעדי רשת תואמים.

#שימוש ב-MCP בשיחה עם הסוכן

קרסור משתמש אוטומטית בכלי MCP המופיעים תחת Available Tools כאשר הם רלוונטיים, כולל במצב תכנון (Plan Mode). ניתן לבקש כלי ספציפי בשמו או לתאר את המשימה הנדרשת. הפעלה או השבתה של שרתי MCP מתבצעת מתוך Customize בסרגל הצד.

#אישורי הרצה ומצבי ריצה (Tool Approval and Run Mode)

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

כלי MCP פועלים לפי אותם מצבי ריצה (Run Modes) של פקודות טרמינל. לדוגמה, במצב Auto-review, כלי MCP שנמצאים ברשימת המאושרים מופעלים מיידית, וכל שאר הכלים מנותבים דרך המסווג (classifier).

קרסור מציג את תגובת הכלי בצ'אט עם תצוגות ניתנות להרחבה של הארגומנטים והתגובות.

#תמונות כהקשר (Images as Context)

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

const RED_CIRCLE_BASE64 = "/9j/4AAQSkZJRgABAgEASABIAAD/2w...";
// ^ full base64 clipped for readability

server.tool("generate_image", async (params) => {
  return {
    content: [
      {
        type: "image",
        data: RED_CIRCLE_BASE64,
        mimeType: "image/jpeg",
      },
    ],
  };
});

קרסור מצרף את התמונות המוחזרות לשיחה. אם מודל ה-AI תומך בתמונות, הוא מנתח אותן.

#ניפוי שגיאות וצפייה בלוגים

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

1. פתחו את חלונית הפלט בקרסור באמצעות Cmd+Shift+U.
2. בחרו באפשרות MCP Logs מתוך התפריט הנפתח.
3. בדקו האם מופיעות שגיאות חיבור, בעיות אימות או קריסות של השרת.

הלוגים מציגים הודעות אתחול שרת, קריאות לכלים והודעות שגיאה.

אם שרת MCP נכשל או מגיע למצב של פסק זמן (Timeout):

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

#כיבוי ועדכון שרתי MCP

#כיבוי זמני של שרת

ניתן להפעיל ולכבות שרתים מבלי להסיר אותם:

1. פתחו את Customize בסרגל הצד.
2. אתרו את שרת ה-MCP שברצונכם לשנות.
3. השתמשו במתג כדי להפעיל או להשבית אותו.

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

#עדכון שרתי MCP

עבור שרתים מבוססי npm:

1. הסירו את השרת מתוך Customize.
2. נקו את מטמון npm באמצעות הפקודה: npm cache clean --force
3. הוסיפו את השרת מחדש כדי לקבל את הגרסה העדכנית ביותר.

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

#עקרונות אבטחה בחיבורי MCP

בעת התקנת שרתי MCP, יש להקפיד על הכללים הבאים:

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

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

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

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

• שילוב עם Xcode: חיבור קרסור ל-Xcode גרסה 26.3 ומעלה לצורך ביצוע Builds, הרצת בדיקות, תצוגות מקדימות של SwiftUI וחיפוש בתיעוד הרשמי של Apple.
• מדריך לפיתוח ווב: שילוב Linear, Figma וכלי דפדפן ישירות בתהליך העבודה של הפיתוח.