پیکربندی سرور MCP «میانای برنامه‌سازی کاربردی افراد»

People API یک سرور Model Context Protocol (MCP) از راه دور ارائه می‌دهد که به عامل‌های هوش مصنوعی امکان می‌دهد به‌طور امن با داده‌های نمایه و مخاطب Google Workspace تعامل داشته باشند. با پیکربندی سرور MCP مربوط به People API، به برنامه‌های هوش مصنوعی مثل Google Antigravity و Claude امکان می‌دهید تا بااستفاده از People API کنش‌هایی را انجام دهند.

سرور MCP «میانای برنامه‌سازی کاربردی افراد» روشی استاندارد برای عوامل هوش مصنوعی فراهم می‌کند تا:

  • خواندن داده‌ها: بازیابی نمایه‌های کاربر و جستجوی مخاطبین یا افراد راهنما.
  • رعایت امنیت: همان اجازه‌ها و کنترل‌های حاکمیت داده کاربر را به‌ارث می‌برد.

پیش‌نیازها

پیکربندی سرور MCP «میانای برنامه‌سازی کاربردی افراد»

برای استفاده از سرور People API MCP، باید آن را در پروژه Google Cloud خود فعال کنید و سپس مشتری MCP خود را برای اتصال به آن پیکربندی کنید.

فعال کردن سرویس MCP و میانای برنامه‌سازی کاربردی

برای استفاده از سرور People API MCP، باید سرویس زیر را در پروژه Google Cloud خود فعال کنید:

  • People API

CLI

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

PROJECT_ID را با شناسه پروژه Google Cloud خودتان جایگزین کنید.

کنسول

میاناهای برنامه‌سازی کاربردی را در کنسول Google Cloud فعال کنید:

فعال کردن میاناهای برنامه‌سازی کاربردی

سرور MCP «میانای برنامه‌سازی کاربردی People» از OAuth 2.0 برای اصالت‌سنجی و صدور مجوز استفاده می‌کند. قبل‌از اینکه بتوانید شناسه مشتری OAuth ایجاد کنید، باید صفحه کسب رضایت OAuth را پیکربندی کنید.

  1. در کنسول Google Cloud، به پلاتفرم اصالت‌سنجی Google > نمانام‌سازی بروید.

    رفتن به نمانام‌سازی

  2. اگر قبلاً پلاتفرم Google Auth را پیکربندی کرده‌اید، می‌توانید تنظیمات «صفحه رضایت OAuth» زیر را در نمانام‌سازی، مخاطب، و دسترسی به داده‌ها پیکربندی کنید. اگر پیامی با این مضمون دیدید: پلاتفرم Google Auth هنوز پیکربندی نشده است، روی شروع به کار کلیک کنید:

    1. در بخش اطلاعات برنامه، در نام برنامه، People API MCP Server را تایپ کنید.
    2. در ایمیل پشتیبانی کاربر، نشانی ایمیل خودتان یا گروه Google مناسبی را انتخاب کنید.
    3. روی بعدی کلیک کنید.
    4. در بخش مخاطبان، داخلی را انتخاب کنید. اگر نمی‌توانید داخلی را انتخاب کنید، خارجی را انتخاب کنید.
    5. روی بعدی کلیک کنید.
    6. در بخش اطلاعات تماس، نشانی ایمیلی وارد کنید که ازطریق آن بتوانید از هرگونه تغییر در پروژه‌تان مطلع شوید.
    7. روی بعدی کلیک کنید.
    8. در بخش تکمیل، خط‌مشی داده‌های کاربر سرویس‌های Google API را مرور کنید و درصورت موافقت، با «خط‌مشی داده‌های کاربر سرویس‌های Google API» موافقم را انتخاب کنید.
    9. روی ادامه کلیک کنید.
    10. روی ایجاد کردن کلیک کنید.
    11. اگر خارجی را برای نوع کاربر انتخاب کرده‌اید، کاربران آزمایشی را اضافه کنید:
      1. روی مخاطبان کلیک کنید.
      2. در بخش کاربران آزمایشی، روی افزودن کاربران کلیک کنید.
      3. نشانی ایمیل خود و سایر کاربران آزمایش مجاز را وارد کنید، سپس روی ذخیره کلیک کنید.

  3. روی دسترسی به داده‌ها > افزودن یا برداشتن محدوده‌ها کلیک کنید. پانلی با فهرست حوزه‌های هر میانای برنامه‌سازی کاربردی که در پروژه Google Cloud فعال کرده‌اید ظاهر می‌شود.

    1. در بخش افزودن دستی محدوده‌ها، محدوده‌های سرور People API MCP را جای‌گذاری کنید:

      • 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 > مشتریان > ایجاد مشتری بروید

      رفتن به «ایجاد مشتری»

    2. برنامه وب را به‌عنوان نوع برنامه انتخاب کنید.

    3. نام را وارد کنید.

    4. در بخش نشانی‌های وب هدایت مجاز، روی + افزودن نشانی وب کلیک کنید، و سپس https://antigravity.google/oauth-callback را در فیلد نشانی‌های وب اضافه کنید.

    5. روی ایجاد کلیک کنید و شناسه کارخواه و رمز کارخواه خود را کپی کنید.

  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 را اصالت‌سنجی کنید. می‌توانید بااستفاده از تنظیمات GUI یا CLI اصالت‌سنجی کنید:

    • برای Antigravity IDE یا GUI (Antigravity 2.0):

      1. صفحه تنظیمات را باز کنید (برای نمونه، روی تنظیمات در پایین سمت راست کلیک کنید یا تنظیمات کاربر ضدجاذبه را باز کنید).
      2. به سفارشی‌سازی‌ها بروید.
      3. در بخش سرورهای MCP نصب‌شده، روی بازآوری کلیک کنید.
      4. people را در فهرست پیدا کنید، روی اصالت‌سنجی کلیک کنید، به سیستم «حساب Google» خود وارد شوید، کد مجوز را کپی کنید، آن را در چارگوش ورودی جای‌گذاری کنید، و روی ارسال کلیک کنید.

    • برای Antigravity CLI:

      1. شروع Antigravity CLI:

        agy

      2. با اجرای دستور زیر، پانل مدیریت تعاملی MCP را باز کنید:

        /mcp

      3. از کلیدهای جهت‌نما برای انتخاب people استفاده کنید، به کنش اصالت‌سنجی بروید، و کلید Enter را فشار دهید. جریان ورود به سیستم را در مرورگرتان تکمیل کنید، کد مجوز را کپی کنید، آن را در پیام‌واره پایانه جای‌گذاری کنید، و کلید ورود را فشار دهید.

  6. تأیید کنید که سرور به‌درستی پیکربندی و اجرا شده است:

    • برای Antigravity IDE یا GUI: دکمه خروج از سیستم در کنار سرور در بخش سفارشی‌سازی‌ها > سرورهای MCP نصب‌شده نمایش داده می‌شود.
    • برای Antigravity CLI: پانل /mcp را باز کنید تا سرورهای MCP پیکربندی‌شده‌تان را ببینید. سرورهای درستی‌سنجی و اصالت‌سنجی‌شده در کنار نامشان در پانل TUI تعاملی، 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 > مشتریان > ایجاد مشتری بروید

      رفتن به «ایجاد کارخواه»

    2. برنامه وب را به‌عنوان نوع برنامه انتخاب کنید.

    3. نام را وارد کنید.

    4. در بخش نشانی‌های وب هدایت مجاز، روی + افزودن نشانی وب کلیک کنید، و سپس https://claude.ai/api/mcp/auth_callback را در فیلد نشانی‌های وب اضافه کنید.

    5. روی ایجاد کلیک کنید و شناسه کارخواه و رمز کارخواه خود را کپی کنید.

  2. سرور MCP را در Claude پیکربندی کنید:

    1. در Claude.ai یا Claude Desktop، به تنظیمات (یا تنظیمات سرپرست) > رابط‌ها بروید.
    2. روی افزودن اتصال‌دهنده سفارشی کلیک کنید.
    3. جزئیات اتصال را برای محصول People API وارد کنید:
      • نام سرور: people.
      • نشانی وب سرور MCP راه دور: https://people.googleapis.com/mcp/v1
    4. در تنظیمات پیشرفته، شناسه کارخواه OAuth و رمز کارخواه OAuth را وارد کنید.
    5. روی افزودن کلیک کنید.

موارد دیگر

بسیاری از برنامه‌های هوش مصنوعی روش‌هایی برای اتصال به سرور MCP ازراه‌دور دارند. معمولاً باید جزئیاتی درباره سرور وارد کنید، مثل نام، نقاط پایانی، پروتکل انتقال، و روش اصالت‌سنجی. برای سرور MCP راه دور People API، موارد زیر را وارد کنید:

برای جزئیات بیشتر درباره متصل کردن انواع مختلف کارخواه‌ها، پیکربندی MCP در برنامه هوش مصنوعی را ببینید.

سرور MCP مربوط به People API را آزمایش کنید

پس‌از پیکربندی کردن کارخواه MCP، می‌توانید اتصال را با اجرا کردن چند پیام‌واره آزمایشی درستی‌سنجی کنید.

سؤالات زیر را از کارخواه MCP خود بپرسید:

  • «طبق «نمایه Google» من، نامم چیست؟»

    کارخواه از people.get_user_profile برای بازیابی اطلاعات نمایه Google Workspace شما استفاده می‌کند.

اگر ابزارها با موفقیت اجرا شوند و پاسخ‌های مرتبط دریافت کنید، سرور MCP «میانای برنامه‌سازی کاربردی افراد» شما به‌درستی پیکربندی شده است.

عیب‌یابی

اگر در اتصال به سرور MCP با مشکل مواجه شدید، می‌توانید خطاها را در گزارش‌های OAuth بررسی کنید. از سرپرستتان بخواهید رویدادهای گزارش OAuth را در ابزار تحقیقات امنیتی بررسی کند.

مرجع ابزار

ابزارهای زیر برای سرور MCP «میانای برنامه‌سازی کاربردی افراد» دردسترس است:

  • get_user_profile
  • search_contacts
  • search_directory_people

ملاحظات امنیتی مهم: تزریق پیام‌واره غیرمستقیم

وقتی مدل زبانی را درمعرض داده‌های غیرقابل‌اعتماد قرار می‌دهید، خطر حمله تزریق پیام‌واره غیرمستقیم وجود دارد. ازآنجایی‌که میزبان‌های MCP مثل Google Antigravity ازطریق سرور MCP «میانای برنامه‌سازی کاربردی» به ابزارها و میاناهای برنامه‌سازی کاربردی قدرتمند دسترسی دارند، می‌توانند داده‌های «حساب Google» شما را بخوانند.

برای کاهش این خطرات، باید پیام‌واره‌ها و پاسخ‌ها را ازنظر محتوای مخرب یا حملات تزریق پیام‌واره غربال کنید. می‌توانید از Model Armor ارائه‌شده توسط Google استفاده کنید یا می‌توانید از راهکار خودتان استفاده کنید، به‌شرطی که آن را مستند کنید تا کاربران بتوانند آن ریسک را بپذیرند. برای اطلاعات بیشتر، پیکربندی امنیت برای سرورهای Google Workspace MCP را ببینید.

این روال‌های مطلوب را دنبال کنید:

  • فقط از ابزارهای مورداعتماد استفاده کنید. هرگز سرور MCP «میانای برنامه‌سازی کاربردی افراد» را به برنامه‌های غیرقابل‌اعتماد یا تأییدنشده متصل نکنید.
  • مراقب ورودی‌های غیرقابل‌اعتماد باشید. از مشتری MCP خود نخواهید منابع را از منابع تأییدنشده پردازش کند. این ورودی‌ها ممکن است حاوی دستورالعمل‌های پنهانی باشند که می‌توانند جلسه شما را ربوده و به مهاجم اجازه دهند داده‌های شما را تغییر دهد، بدزدد یا حذف کند.
  • همه کنش‌ها را مرور کنید. همیشه کنش‌های انجام‌شده توسط مشتری هوش مصنوعی خود را ازطرف خودتان به‌دقت بررسی کنید تا مطمئن شوید درست هستند و با اهداف شما مطابقت دارند.