📘 תיעוד 4

פרוטוקול Model Context Protocol (MCP)

#מה זה MCP?

Model Context Protocol (MCP) מאפשר ל-Cursor להתחבר לכלים חיצוניים ולמקורות נתונים. התקן ונהל שרתי MCP מדף Customize או הגדר אותם ב-mcp.json.

#למה להשתמש ב-MCP?

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

כתוב שרתי MCP בכל שפה שיכולה להדפיס ל-stdout או לשרת נקודת קצה של HTTP: פייתון, JavaScript, Go וכו'.

עיין בתוספים רשמיים ב-Cursor Marketplace. עבור תוספי קהילה ושרתי MCP, עיין ב-cursor.directory.

#איך זה עובד

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

Cursor תומך בשלוש שיטות תעבורה:

#תמיכה בפרוטוקול ובהרחבות

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

#יישומי MCP

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

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

#התקנת שרתי MCP

#התקנה בלחיצה אחת

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

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

#שימוש ב-mcp.json

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

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

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

// MCP server using HTTP or SSE - runs on a server
{
  "mcpServers": {
    "server-name": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "API_KEY": "value"
      }
    }
  }
}

#OAuth סטטי עבור שרתים מרוחקים

עבור שרתי 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"]
      }
    }
  }
}

#כתובת URL סטטית להפניה מחדש

Cursor משתמש בכתובות URL קבועות להפניה מחדש של OAuth עבור שרתי MCP. רשום את ה-callback עבור כל ממשק שהמשתמשים שלך מבצעים ממנו אימות:

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

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

בעת הגדרת אפליקציית ה-OAuth של ספק ה-MCP, רשום את שתי כתובות ה-URL ככתובות URI מורשות להפניה מחדש אם משתמשים מבצעים אימות הן מהאינטרנט והן משולחן העבודה. השרת מזוהה באמצעות פרמטר ה-state של OAuth, ולכן כתובות URL אלו להפניה מחדש פועלות עבור כל שרתי ה-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, Cursor מספק extension API המאפשר הגדרה דינמית ללא שינוי קובצי mcp.json. הדבר שימושי במיוחד לסביבות ארגוניות ולתהליכי התקנה אוטומטיים.

#הפניה ל-Extension API

רשום שרתי MCP באופן תכנותי באמצעות vscode.cursor.mcp.registerServer()

#מיקומי הגדרות

#הגדרות פרויקט

צור את .cursor/mcp.json בפרויקט שלך עבור כלים ספציפיים לפרויקט.

#הגדרות גלובליות

צור את ~/.cursor/mcp.json בספריית הבית שלך עבור כלים הזמינים בכל מקום.

#אינטרפולציה של הגדרות

השתמש במשתנים בערכים של mcp.json. Cursor מפענח משתנים בשדות אלה: 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}"
      }
    }
  }
}

#אימות

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

Cursor תומך ב-OAuth עבור שרתים הדורשים זאת.

#בקרות מנהל ארגוני

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

#הפצת MCP צוותית

הגדר שרתי MCP צוותיים משותפים תחת Dashboard > Plugins & MCPs. שרתים אלה זמינים ל-Cloud Agents.

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

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

#רשימת היתרים ל-MCP

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

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

• רשומות פקודה מאשרות שרתי MCP מקומיים מסוג stdio לפי תבנית פקודה.
• רשומות URL מאשרות שרתי MCP מרוחקים מסוג HTTP/SSE לפי תבנית רשומת URL.
• רשימות היתרים לכלים מגבילות אילו כלים מתוך שרת מאושר יכולים לרוץ באופן אוטומטי. השארת רשימת היתרים לכלים ריקה מאפשרת את כל הכלים מאותו שרת.

#בקרות רשת

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

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

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

#הרחבות MCP של משתמשים

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

#שימוש ב-MCP בצ'אט

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

#אישור כלים

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

#מצב הרצה

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

#תגובת הכלי

Cursor מציג את התגובה בצ'אט עם תצוגות ניתנות להרחבה של ארגומנטים ותגובות:

#תמונות כהקשר

שרתי 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",
      },
    ],
  };
});

עיין ב-שרת לדוגמה זה לפרטי יישום. Cursor מצרף תמונות שהוחזרו לצ'אט. אם המודל תומך בתמונות, הוא מנתח אותן.

#שיקולי אבטחה

בעת התקנת שרתי MCP, שקול את נוהלי האבטחה הבאים:

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

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

#דוגמאות מהעולם האמיתי

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

• אינטגרציה עם Xcode: חבר את Cursor ל-Xcode 26.3+ עבור בניות, בדיקות, תצוגות מקדימות של SwiftUI וחיפוש בתיעוד של Apple
• מדריך לפיתוח אתרים: שלב את Linear, Figma וכלי דפדפן בתהליך הפיתוח שלך

#שאלות נפוצות

#מה המטרה של שרתי MCP?

שרתי MCP מחברים את Cursor לכלים חיצוניים כמו Google Drive, Notion ושירותים אחרים כדי להביא מסמכים ודרישות לתוך תהליך העבודה שלך בכתיבת קוד.

#איך אני מאתר תקלות בשרת MCP?

הצג יומני MCP על ידי:

1. פתח את חלונית ה-Output ב-Cursor (Cmd+Shift+U)
2. בחר "MCP Logs" מהתפריט הנפתח
3. בדוק שגיאות חיבור, בעיות אימות או קריסות שרת

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

#האם אני יכול להשבית שרת MCP באופן זמני?

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

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

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

#מה קורה אם שרת MCP קורס או חורג מזמן ההמתנה?

אם שרת MCP נכשל:

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

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

#איך מעדכנים שרת MCP?

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

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

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

#האם אני יכול להשתמש בשרתי MCP עם נתונים רגישים?

כן, אך פעל לפי נוהלי אבטחה מומלצים:

• השתמש במשתני סביבה עבור סודות, לעולם אל תטמיע אותם ישירות בקוד
• הרץ שרתים רגישים באופן מקומי עם תעבורת stdio
• הגבל הרשאות מפתחות API למינימום הנדרש
• בדוק את קוד השרת לפני חיבור למערכות רגישות
• שקול להריץ שרתים בסביבות מבודדות

#נושאים קשורים

• עזרה בנושא MCP

#מפת האתר

סקירה כללית של כל דפי התיעוד