הגדרת שרת MCP של People API

תצוגה מקדימה למפתחים: זמינה כחלק מתוכנית התצוגה המקדימה למפתחים של Google Workspace, שמעניקה גישה מוקדמת לתכונות מסוימות.

‫People API מציע שרת Model Context Protocol‏ (MCP) מרוחק, שמאפשר לסוכני AI לקיים אינטראקציה מאובטחת עם נתוני הפרופיל ואנשי הקשר ב-Google Workspace. כשמגדירים את שרת ה-MCP של People API, מאפשרים לאפליקציות מבוססות-AI כמו Google Antigravity ו-Claude לבצע פעולות באמצעות People API.

שרת ה-MCP של People API מספק לסוכני AI דרך סטנדרטית:

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

דרישות מוקדמות

• חברות בתוכנית Google Workspace Developer Preview.

• פרויקט ב-Google Cloud. כדי ליצור פרויקט, קראו את המאמר יצירת פרויקט.

• מארח של MCP, כמו Google Antigravity.

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

  1. מתקינים את Google Cloud CLI. אם התקנתם את ה-CLI של gcloud, השתמשו בפקודה gcloud components update כדי לבדוק אם הגרסה העדכנית מותקנת.
  2. אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות. איך נכנסים ל-CLI של gcloud באמצעות הזהות המאוחדת?
  3. מאתחלים את ה-CLI של gcloud.

הגדרת שרת ה-MCP של People API

כדי להשתמש בשרת MCP של People API, צריך להפעיל אותו בפרויקט בענן ב-Google Cloud ואז להגדיר את לקוח ה-MCP כך שיתחבר אליו.

הפעלת שירות ה-API וה-MCP

כדי להשתמש בשרת MCP של People API, צריך להפעיל את השירות הבא בפרויקט ב-Google Cloud:

• People API

CLI

gcloud services enable people.googleapis.com --project=PROJECT_ID

מחליפים את PROJECT_ID במזהה הפרויקט ב-Google Cloud.

המסוף

מפעילים את ממשקי ה-API במסוף Google Cloud:

הפעלת ממשקי ה-API

הגדרת מסך ההסכמה ל-OAuth

שרת ה-MCP של People API משתמש ב-OAuth 2.0 לאימות ולהרשאה. כדי ליצור מזהה לקוח OAuth, צריך להגדיר קודם את מסך ההסכמה ל-OAuth.

1. במסוף Google Cloud, נכנסים לדף Google Auth Platform > Branding.

   מעבר לדף Branding

2. אם כבר הגדרתם את פלטפורמת האימות של Google, אתם יכולים לקבוע את ההגדרות הבאות של מסך ההסכמה ל-OAuth בקטעים Branding,‏ Audience וData Access. אם מופיעה ההודעה Google Auth Platform not configured yet, לוחצים על Get Started:

   1. בקטע App Information (פרטי האפליקציה), בשדה App name (שם האפליקציה), מקלידים People API MCP Server.
   2. בקטע User support email, בוחרים את כתובת האימייל שלכם או קבוצה מתאימה ב-Google.
   3. לוחצים על הבא.
   4. בקטע Audience, לוחצים על Internal. אם אי אפשר לבחור באפשרות פנימי, בוחרים באפשרות חיצוני.
   5. לוחצים על הבא.
   6. בקטע Contact Information, מזינים כתובת אימייל שאליה אפשר לשלוח התראות על שינויים בפרויקט.
   7. לוחצים על הבא.
   8. בקטע Finish, קוראים את המדיניות של Google בנושא נתוני משתמשים בשירותי API. אם אתם מסכימים, סמנו את התיבה I agree to the Google API Services: User Data Policy.
   9. לוחצים על המשך.
   10. לוחצים על יצירה.
   11. אם בחרתם באפשרות חיצוני בתור סוג המשתמש, הוסיפו משתמשי בדיקה:
       1. לוחצים על קהל.
       2. בקטע משתמשי בדיקה, לוחצים על הוספת משתמשים.
       3. מזינים את כתובת האימייל שלכם ושל משתמשי בדיקה מורשים אחרים, ולוחצים על Save.

3. לוחצים על גישה לנתונים > הוספה או הסרה של היקפי הרשאה. מופיע חלונית עם רשימת היקפי ההרשאות לכל API שהפעלתם בפרויקט ב-Google Cloud.

   1. בקטע הוספה ידנית של היקפי הרשאות, מדביקים את היקפי ההרשאות של שרת ה-MCP של People API:

      • https://www.googleapis.com/auth/directory.readonly
      • https://www.googleapis.com/auth/userinfo.profile
      • https://www.googleapis.com/auth/contacts.readonly

   2. לוחצים על הוספה לטבלה.

   3. לוחצים על עדכון.

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

הגדרת לקוח ה-MCP

כדי להוסיף את שרת ה-MCP המרוחק של People API ללקוח ה-MCP, פועלים לפי ההוראות של הלקוח.

Antigravity

כדי להוסיף את שרת ה-MCP המרוחק של People API ל-Antigravity, צריך להוסיף את הגדרות השרת לקובץ mcp_config.json. ההוראות האלה רלוונטיות ל-Antigravity 2.0, ל-Antigravity IDE ול-Antigravity CLI.

1. יוצרים מזהה לקוח וסוד לקוח ב-OAuth 2.0:

   1. במסוף Google Cloud, עוברים אל Google Auth Platform > Clients > Create Client.

      מעבר אל Create Client

   2. בוחרים באפשרות Web application (אפליקציית אינטרנט) כסוג האפליקציה.

   3. הזן שם.

   4. בקטע Authorized redirect URIs, לוחצים על ‎+ Add URI ומוסיפים את https://antigravity.google/oauth-callback בשדה URIs.

   5. בוחרים באפשרות שימוש בלקוח הזה לסוכן מבוסס-AI.

   6. לוחצים על Create ומעתיקים את מזהה לקוח ואת סוד לקוח.

2. פותחים או יוצרים את קובץ התצורה ~/.gemini/config/mcp_config.json.

3. מוסיפים את ההגדרה mcpServers ל-mcp_config.json:

   {
     "mcpServers": {
       "people": {
         "serverUrl": "https://people.googleapis.com/mcp/v1",
         "oauth": {
           "clientId": "OAUTH_CLIENT_ID",
           "clientSecret": "OAUTH_CLIENT_SECRET"
         }
       }
     }
   }
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫OAUTH_CLIENT_ID: מזהה הלקוח שיצרתם.
   • ‫OAUTH_CLIENT_SECRET: סוד הלקוח שיצרתם.

4. חיסכון של mcp_config.json.

5. מאמתים את שרת ה-MCP. אפשר לבצע אימות באמצעות הגדרות ממשק המשתמש הגרפי או ה-CLI:

   • ב-Antigravity IDE או GUI (Antigravity 2.0):

     1. פותחים את מסך ההגדרות (למשל, לוחצים על Settings בפינה השמאלית התחתונה או פותחים את Antigravity User Settings).
     2. עוברים אל התאמות אישיות.
     3. בקטע שרתי MCP מותקנים, לוחצים על רענון.
     4. מוצאים את people ברשימה, לוחצים על Authenticate, נכנסים לחשבון Google, מעתיקים את קוד ההרשאה, מדביקים אותו בתיבת הדו-שיח של הקלט ולוחצים על Submit.

   • ב-Antigravity CLI:

     1. מפעילים את Antigravity CLI:

        agy
        

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

        /mcp
        

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

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

   • ב-Antigravity IDE או GUI: הכפתור Sign out מופיע ליד שרת ה-MCP בקטע Customizations > Installed MCP Servers.
   • ב-Antigravity CLI: פותחים את החלונית /mcp כדי לראות את שרתי ה-MCP שהגדרתם. שרתים מאומתים מוצגים עם הכיתוב Authed לצד השמות שלהם בחלונית האינטראקטיבית של ממשק המשתמש בטקסט. אתם יכולים לבחור כל שרת בתצוגת מרכז הבקרה כדי לבדוק את הסטטוס שלו ולראות את כל הכלים הזמינים בו.

שרת ה-MCP המרוחק מוכן לשימוש ב-Antigravity.

Claude

כדי להשתמש בשרת ה-MCP המרוחק של People API עם Claude.ai או Claude Desktop, צריך מינוי ל-Claude Enterprise, ‏Pro, ‏Max או Team.

כדי להוסיף את שרת ה-MCP המרוחק של People API ל-Claude, צריך להגדיר מחבר מותאם אישית עם מזהה לקוח וסוד לקוח ב-OAuth.

1. יוצרים מזהה לקוח וסוד ב-OAuth 2.0:

   1. במסוף Google Cloud, נכנסים לדף Google Auth Platform > Clients > Create Client.

      מעבר אל Create Client

   2. בוחרים באפשרות אפליקציית אינטרנט בתור סוג האפליקציה.

   3. הזן שם.

   4. בקטע Authorized redirect URIs (כתובות URI מורשות להפניה אוטומטית), לוחצים על + Add URI (הוספת כתובת URI) ואז מוסיפים את https://claude.ai/api/mcp/auth_callback בשדה URIs (כתובות URI).

   5. בוחרים באפשרות שימוש בלקוח הזה לסוכן מבוסס-AI.

   6. לוחצים על Create (יצירה) ומעתיקים את Client ID (מזהה הלקוח) ואת Client Secret (סוד הלקוח).

2. מגדירים את שרת ה-MCP ב-Claude:

   1. ב-Claude.ai או ב-Claude Desktop, עוברים אל Settings (הגדרות) (או אל Admin settings (הגדרות אדמין)) > Connectors (מחברים).
   2. לוחצים על הוספת מחבר בהתאמה אישית.
   3. מזינים את פרטי החיבור למוצר People API:
      • Server name: ‏people.
      • כתובת ה-URL של שרת ה-MCP המרוחק: https://people.googleapis.com/mcp/v1
   4. בקטע Advanced settings, מזינים את מזהה הלקוח ב-OAuth ואת סוד הלקוח ב-OAuth.
   5. לוחצים על הוספה.

אחרים

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

• שם השרת: people

• כתובת ה-URL של השרת: https://people.googleapis.com/mcp/v1

• תעבורה: HTTP שניתן להעביר בסטרימינג

• אימות: שרת ה-MCP המרוחק של People API משתמש ב-OAuth 2.0. כשיוצרים את לקוח OAuth 2.0, בוחרים באפשרות Use this client for an agent מבוסס-AI. פרטים נוספים זמינים במאמר מידע על אימות והרשאה.

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

בדיקת שרת ה-MCP של People API

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

אפשר לנסות לשאול את לקוח ה-MCP את השאלות הבאות:

• "מה השם שלי לפי הפרופיל ב-Google?"

  הלקוח משתמש ב-people.get_user_profile כדי לאחזר את פרטי הפרופיל שלכם ב-Google Workspace.

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

פתרון בעיות

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

הפניה לכלי

הכלים הבאים זמינים בשרת ה-MCP של People API:

• get_user_profile
• search_contacts
• search_directory_people

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

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

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

כדאי לפעול לפי השיטות המומלצות הבאות:

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

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

• הגדרת האבטחה של שרתי MCP של Google Workspace
• שרתי MCP של Google Workspace ב-Antigravity (שיעור Lab לתכנות)
• רשימת שרתי MCP של Google Workspace