רישום שרתי MCP

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

במאמר הזה מוסבר איך לרשום שרתי MCP ואיך מנהלים את מפרטי הכלים שלהם ב-Agent Registry.

גילוי אוטומטי של שרתי MCP Google Cloud

שרתי MCP רשמיים של Google ושל Google Cloud נרשמים באופן אוטומטי ב-Agent Registry. רשימה של שרתי MCP של Google ושרתי MCP מרוחקים של Google Cloud זמינה במוצרים נתמכים במסמכי התיעוד שלGoogle Cloud שרתי MCP.

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

רישום שרתי MCP מ-GKE

אפשר להגדיר רישום אוטומטי לשרתי MCP בהתאמה אישית שנפרסו ב-Google Kubernetes Engine ‏ (GKE) על ידי הוספת התווית registry.gke.io/functional-type: "MCP_SERVER" לפריסות GKE.

כדי לאפשר ל-Agent Registry לבצע סריקת אינטרוספקציה ולגלות את כלי ה-MCP, הפריסה צריכה לכלול גם הערות שמצהירות על כתובות נקודות הקצה של השרת ועל פרטי היכולות. בנוסף, מגדירים את Workload Identity באמצעות ההערה iam.gke.io/spiffe-identity-type: agent-identity כדי לאפשר תקשורת מאובטחת ומאומתת.

בדוגמה הבאה מוצג מניפסט של פריסת שרת MCP ב-GKE באמצעות ההגדרות האלה.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-mcp-server
  labels:
    # GKE takes this label and registers the deployment as an MCP server to the registry
    registry.gke.io/functional-type: "MCP_SERVER"
  annotations:
    # A list of endpoint URLs where the GKE controller can access this MCP server
    modelcontextprotocol.info/urls: |
      - https://my-mcp-server.default.svc.cluster.local/mcp
    # Defines structural capabilities for the MCP server card
    modelcontextprotocol.info/capabilities: |
      card:
        endpoint: "/mcp"
        protocol: "HTTP"
spec:
  selector:
    matchLabels:
      app: my-mcp-server
  template:
    metadata:
      annotations:
        # Workload Identity annotation for identity and access management
        iam.gke.io/spiffe-identity-type: agent-identity
      labels:
        app: my-mcp-server
    spec:
      containers:
      - name: server
        image: gcr.io/my-project/my-mcp-server:1.0.0

כשמחילים את הפריסה, GKE מנסה באופן אוטומטי לקבל את מפרט הכלי מהשרת ולרשום את הכלים ישירות במודל הנתונים של מאגר הסוכנים.

רישום שרתי MCP חיצוניים

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

כשרושמים שרת MCP באופן ידני, Agent Registry רושם את נקודת הקצה. עם זאת, הוא לא בודק אוטומטית את השרת כדי לקבוע אילו כלים זמינים. כדי לאפשר למשתמשים לגלות את הכלים המדויקים שזמינים בשרת ה-MCP שלכם, אתם צריכים לספק את מפרטי הכלים במהלך ההרשמה על ידי העלאה של קובץ toolspec.json.

לפני שמתחילים

לפני שמתחילים, צריך להגדיר את Agent Registry. כדי לבצע את המשימות האלה, צריך מזהה פרויקט.

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

התפקידים הנדרשים

כדי לקבל את ההרשאות שנדרשות לרישום ידני של שרתי MCP ב-Agent Registry, צריך לבקש מהאדמין להקצות לכם ב-IAM את התפקיד Agent Registry API Editor (roles/agentregistry.editor) בפרויקט. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

הכנת מפרט הכלי

יוצרים קובץ toolspec.json שמתאר את הכלים שהשרת מספק. גודל הקובץ המקסימלי של קובץ המפרט הזה הוא 10 KB.

קובץ ה-JSON צריך להיות תואם למפרט MCP של סכימות כלי, לדוגמה:

{
  "tools": [
    {
      "name": "get_customer_info",
      "description": "Retrieves customer details from the database.",
      "annotations": {
        "title": "Get Customer Info",
        "readOnlyHint": true,
        "idempotentHint": true
      }
    },
    {
      "name": "create_support_ticket",
      "description": "Creates a new support ticket in the issue tracking system.",
      "annotations": {
        "title": "Create Support Ticket",
        "destructiveHint": true,
        "idempotentHint": false,
        "openWorldHint": true
      }
    }
  ]
}

לדרישות מפורטות בנוגע למבנה, אפשר לעיין בסכימות JSON ובהפניית REST.

רישום השרת והכלים

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

המסוף

  1. במסוף Google Cloud , עוברים אל Agent Registry:

    כניסה ל-Agent Registry

  2. בכלי לבחירת פרויקטים, בוחרים את הפרויקט שבו הגדרתם את Agent Registry. Google Cloud

  3. בוחרים בכרטיסייה שרתי MCP.

  4. לוחצים על הוספת שרת MCP.

  5. בחלונית פרטים של שרת MCP, מזינים את השם המוצג, תיאור ואת האזור הגיאוגרפי.

  6. בקטע Tool specification (מפרט הכלי), מזינים את כתובת ה-URL של נקודת הקצה של שרת ה-MCP ומדביקים את התוכן של קובץ toolspec.json.

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

  7. לוחצים על הבא.

    בחלונית Select MCP tools מוצגת רשימת כלים עם שמות ותיאורים משרת ה-MCP.

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

  9. לוחצים על Save.

gcloud

רושמים את שרת ה-MCP במפרט הכלי:

gcloud agent-registry services create SERVER_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --mcp-server-spec-type=tool-spec \
  --mcp-server-spec-content=toolspec.json \
  --interfaces=url=SERVER_URL,protocolBinding=PROTOCOL

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

  • ‫SERVER_NAME: השם שרוצים לתת לשרת ה-MCP, לדוגמה, custom-mcp-server.
  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫REGION: האזור של המאגר.
  • ‫DISPLAY_NAME: השם שאתם רוצים לתת לשרת, לדוגמה, Custom MCP Server.
  • ‫SERVER_URL: כתובת ה-URL של נקודת הקצה של שרת ה-MCP, לדוגמה, https://api.example.com/mcp.
  • ‫PROTOCOL: פרוטוקול הקישור של נקודת הקצה. הערכים התקינים הם JSONRPC,‏ HTTP_JSON או GRPC. בשרתי MCP, הערך הזה הוא לרוב JSONRPC.

Terraform

כדי לרשום שרת MCP ולציין את הכלים שלו, צריך להגדיר משאב google_agent_registry_service עם הבלוק mcp_server_spec:

resource "google_agent_registry_service" "mcp_server" {
  location     = "REGION"
  service_id   = "SERVER_NAME"
  display_name = "DISPLAY_NAME"
  description  = "An external MCP server registered using Terraform."

  interfaces {
    url              = "SERVER_URL"
    protocol_binding = "JSONRPC"
  }

  mcp_server_spec {
    type    = "NO_SPEC"
  }
}

output "server_resource_name" {
  description = "The generated read-only Server resource name."
  value       = google_agent_registry_service.mcp_server.registry_resource
}

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

  • ‫REGION: האזור של המאגר.
  • ‫SERVER_NAME: השם שרוצים לתת לשרת ה-MCP, לדוגמה, custom-mcp-server.
  • ‫DISPLAY_NAME: השם שאתם רוצים לתת לשרת, לדוגמה, Custom MCP Server.
  • ‫SERVER_URL: כתובת ה-URL של נקודת הקצה של שרת ה-MCP, לדוגמה, https://api.example.com/mcp.

אימות הרישום

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