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

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

سرور MCP مربوط به People API روشی استانداردشده برای عامل‌های هوش مصنوعی فراهم می‌کند تا:

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

پیش‌نیازها

پیکربندی سرور MCP میانای برنامه‌سازی کاربردی People

برای استفاده از سرور MCP مربوط به People API، باید آن را در پروژه 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 Auth > نمانام‌سازی بروید.

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

  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 server را جای‌گذاری کنید:

      • 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. استفاده از این کارخواه برای عامل مجهز به هوش مصنوعی را انتخاب کنید.

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

  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 را انتخاب کنید، به کنش اصالت‌سنجی بروید، و کلید ورود را فشار دهید. جریان ورود به سیستم را در مرورگرتان تکمیل کنید، کد مجوز را کپی کنید، آن را در پیام‌واره پایانه جای‌گذاری کنید، و کلید ورود را فشار دهید.

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

    • برای Antigravity IDE یا GUI: دکمه خروج از سیستم در کنار سرور در بخش سفارشی‌سازی‌ها > سرورهای MCP نصب‌شده نمایش داده می‌شود.
    • برای Antigravity CLI: پانل /mcp را باز کنید تا سرورهای MCP پیکربندی‌شده‌تان را ببینید. سرورهای درستی‌سنجی‌شده و اصالت‌سنجی‌شده اصالت‌سنجی‌شده را در کنار نامشان در پانل تعاملی TUI نمایش می‌دهند. می‌توانید هر سروری را در نمای داشبورد انتخاب کنید تا وضعیت آن را بررسی کنید و فهرست همه ابزارهای دردسترس آن را ببینید.

سرور MCP از دور آماده استفاده در Antigravity است.

Claude

برای استفاده از سرور MCP از دور People API با Claude.ai یا Claude Desktop، باید طرح Claude Enterprise،‏ Pro،‏ Max، یا Team را داشته باشید.

برای افزودن سرور MCP راه دور «میانای برنامه‌سازی کاربردی افراد» به Claude، اتصال‌دهنده سفارشی را با رمز و شناسه کارخواه OAuth پیکربندی کنید.

  1. شناسه و رمز کارخواه OAuth 2.0 ایجاد کنید:

    1. در کنسول Google Cloud، به Google Auth Platform > Clients > Create Client بروید

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

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

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

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

    5. استفاده از این کارخواه برای عامل مجهز به هوش مصنوعی را انتخاب کنید.

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

  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، موارد زیر را وارد کنید:

  • نام سرور: people

  • نشانی وب سرور: https://people.googleapis.com/mcp/v1

  • انتقال: HTTP قابل جاری‌سازی

  • اصالت‌سنجی: سرور MCP راه دور People API از OAuth 2.0 استفاده می‌کند. هنگام ایجاد کارخواه OAuth 2.0، استفاده از این کارخواه برای عامل مجهز به هوش مصنوعی را انتخاب کنید. برای جزئیات، به آشنایی با اصالت‌سنجی و صدور مجوز مراجعه کنید.

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

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

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

پرسش‌های زیر را از مشتری MCP خود بپرسید:

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

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

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

عیب‌یابی

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

مرجع ابزار

ابزارهای زیر برای سرور MCP مربوط به People API دردسترس است:

  • get_user_profile
  • search_contacts
  • search_directory_people

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

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

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

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

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