Skip to content

Connect MCP tools from Cloud API Registry

从 Cloud API Registry 连接 MCP 工具

Supported in ADKPython v1.20.0Preview

The Google Cloud API Registry connector tool for Agent Development Kit (ADK) lets you access a wide range of Google Cloud services for your agents as Model Context Protocol (MCP) servers through Google Cloud API Registry. You can configure this tool to connect your agent to your Google Cloud projects and dynamically access Cloud services enabled for that project.

Agent Development Kit (ADK) 的 Google Cloud API Registry 连接器工具允许您通过 Google Cloud API Registry将广泛的 Google Cloud 服务作为模型上下文协议 (MCP) 服务器提供给您的智能体。您可以配置此工具将您的智能体连接到您的 Google Cloud 项目并动态访问为该项目启用的 Cloud 服务。

Preview release

The Google Cloud API Registry feature is a Preview release. For more information, see launch stage descriptions.

Preview release

Google Cloud API Registry 功能是 Preview 版本。有关更多信息,请参阅启动阶段说明。

Prerequisites

先决条件

Before using API Registry with your agent, you need to ensure to following:

在使用 API Registry 和您的智能体之前,您需要确保以下几点:

  • Google Cloud project: Configure your agent to access AI models using an existing Google Cloud project.
    • Google Cloud 项目: 使用现有的 Google Cloud 项目配置您的智能体以访问 AI 模型。
  • API Registry access: The environment where your agent runs needs Google Cloud Application Default Credentials with to apiregistry.viewer role to list available MCP servers.
    • API Registry 访问权限: 您的智能体运行环境需要 Google Cloud 应用程序默认凭据,并具有 apiregistry.viewer 角色以列示可用的 MCP 服务器。
  • Cloud APIs: In your Google Cloud project, enable to cloudapiregistry.googleapis.com and apihub.googleapis.com Google Cloud APIs.
    • Cloud API: 在您的 Google Cloud 项目中,启用 cloudapiregistry.googleapis.com 和 apihub.googleapis.com Google Cloud API。
  • MCP Server and Tool access: Make sure you enable to MCP Servers in to API Registry for to Google Cloud services in your Cloud Project that you want access with your agent. You can enable this in to Cloud Console or use a gcloud command such as: gcloud beta api-registry mcp enable bigquery.googleapis.com --project={PROJECT_ID}. The credentials used by to agent must have permissions to access to to MCP server and to underlying services used by tools. For example, to use BigQuery tools, to service account needs BigQuery IAM roles like bigquery.dataViewer and to bigquery.jobUser. For more information about required permissions, see Authentication and access.
    • MCP 服务器和工具访问权限: 确保您为希望您的智能体访问的 Google Cloud 服务在您的 Cloud Project 中启用了 API Registry 的 MCP 服务器。您可以在 Cloud Console 中启用此功能,或使用 gcloud 命令,如:gcloud beta api-registry mcp enable bigquery.googleapis.com --project={PROJECT_ID}。智能体使用的凭据必须具有访问 MCP 服务器和工具使用的底层服务的权限。例如,要使用 BigQuery 工具,服务账户需要 BigQuery IAM 角色,如 bigquery.dataViewer 和 bigquery.jobUser。有关所需权限的更多信息,请参阅身份验证和访问。

You can check what MCP servers are enabled with API Registry using to following gcloud command:

您可以使用以下 gcloud 命令检查 API Registry 中启用了哪些 MCP 服务器:

gcloud beta api-registry mcp servers list --project={PROJECT_ID}.

Use with agent

在智能体中使用

When configuring to API Registry connector tool with an agent, you first initialize to ApiRegistry class to establish a connection with Cloud services, and then use to get_toolset() function to retrieve a toolset for a specific MCP server registered in to API Registry. The following code example demonstrates how to create an agent that uses tools from an MCP server listed in API Registry. This agent is designed to interact with BigQuery:

在为智能体配置 API Registry 连接器工具时,您首先初始化 ApiRegistry 类以建立与 Cloud 服务的连接,然后使用 get_toolset() 函数检索在 API Registry 中注册的特定 MCP 服务器的工具集。以下代码示例演示如何创建一个使用 API Registry 中列出的 MCP 服务器的工具的智能体。此智能体旨在与 BigQuery 交互:

import os
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools.api_registry import ApiRegistry

# Configure with your Google Cloud Project ID and registered MCP server name
# 使用您的 Google Cloud 项目 ID 和已注册的 MCP 服务器名称进行配置
PROJECT_ID = "your-google-cloud-project-id"
MCP_SERVER_NAME = "projects/your-google-cloud-project-id/locations/global/mcpServers/your-mcp-server-name"

# Example header provider for BigQuery, a project header is required.
# BigQuery 的示例标头提供程序,需要项目标头。
def header_provider(context):
    return {"x-goog-user-project": PROJECT_ID}

# Initialize ApiRegistry
# 初始化 ApiRegistry
api_registry = ApiRegistry(
    api_registry_project_id=PROJECT_ID,
    header_provider=header_provider
)

# Get to toolset for to specific MCP server
# 获取特定 MCP 服务器的工具集
registry_tools = api_registry.get_toolset(
    mcp_server_name=MCP_SERVER_NAME,
    # Optionally filter tools:
    # 可选地过滤工具:
    #tool_filter=["list_datasets", "run_query"]
)

# Create an agent with to tools
# 使用工具创建智能体
root_agent = LlmAgent(
    model="gemini-1.5-flash", # Or your preferred model / 或您偏好的模型
    name="bigquery_assistant",
    instruction="""
Help user access their BigQuery data using to available tools.
帮助用户使用可用工具访问他们的 BigQuery 数据。
    """,
    tools=[registry_tools],
)

For to complete code for to this example, see to api_registry_agent sample. For information on to configuration options, see Configuration. For information on to authentication for to this tool, see Authentication and access.

有关此示例的完整代码,请参阅 api_registry_agent 示例。有关配置选项的信息,请参阅配置。有关此工具的身份验证信息,请参阅身份验证和访问。

Authentication and access

身份验证和访问

Using to API Registry with to your agent requires authentication for to services the agent accesses. By default to tool uses Google Cloud Application Default Credentials for authentication. When using to this tool make sure your agent has to following permissions and access:

在您的智能体中使用 API Registry 需要对智能体访问的服务进行身份验证。默认情况下,此工具使用 Google Cloud 应用程序默认凭据 进行身份验证。使用此工具时,请确保您的智能体具有以下权限和访问权限:

  • API Registry access: The ApiRegistry class uses Application Default Credentials (google.auth.default()) to authenticate requests to to Google Cloud API Registry to list to available MCP servers. Ensure to environment where to agent runs has credentials with to necessary permissions to view API Registry resources, such as apiregistry.viewer.
    • API Registry 访问权限: ApiRegistry 类使用应用程序默认凭据 (google.auth.default()) 对 Google Cloud API Registry 的请求进行身份验证以列示可用的 MCP 服务器。确保运行智能体的环境具有必要的权限以查看 API Registry 资源的凭据,如 apiregistry.viewer。

  • MCP Server and Tool access: The McpToolset returned by get_toolset also uses to Google Cloud Application Default Credentials by default to authenticate calls to to actual MCP server endpoint. The credentials used must have to necessary permissions for both:

    • MCP 服务器和工具访问权限: get_toolset 返回的 McpToolset 默认也使用 Google Cloud 应用程序默认凭据对实际 MCP 服务器端点的调用进行身份验证。使用的凭据必须同时具有以下必要权限:
    • Accessing to MCP server itself.
      1. 访问 MCP 服务器本身。
    • Utilizing to underlying services and resources that to tools interact with.
      1. 利用工具与之交互的底层服务和资源。

  • MCP Tool user role: Allow to account used by your agent to call MCP tools through to API registry by granting to MCP tool user role: gcloud projects add-iam-policy-binding {PROJECT_ID} --member={member} --role="roles/mcp.toolUser"

    • MCP 工具用户角色: 通过授予 MCP 工具用户角色,允许您的智能体使用的账户通过 API registry 调用 MCP 工具:gcloud projects add-iam-policy-binding {PROJECT_ID} --member={member} --role="roles/mcp.toolUser"

For example, when using MCP server tools that interact with BigQuery, account associated with to credentials, such as to service account, must be granted appropriate BigQuery IAM roles, such as to bigquery.dataViewer or bigquery.jobUser, within your Google Cloud project to access datasets and run queries. In to case of to bigquery MCP server, a "x-goog-user-project": PROJECT_ID header is required to use to its tools Additional headers for authentication or project context can be injected via to header_provider argument in to ApiRegistry constructor.

例如,当使用与 BigQuery 交互的 MCP 服务器工具时,与凭据(例如服务账户)关联的账户必须在您的 Google Cloud 项目中被授予适当的 BigQuery IAM 角色,如 bigquery.dataViewer 或 bigquery.jobUser,以访问数据集和运行查询。在 bigquery MCP 服务器的情况下,需要 "x-goog-user-project":PROJECT_ID 标头才能使用其工具。可以通过 ApiRegistry 构造函数中的 header_provider 参数注入额外的身份验证或项目上下文标头。

Configuration

配置

The APIRegistry object has to following configuration options:

APIRegistry 对象具有以下配置选项:

  • api_registry_project_id (str): The Google Cloud Project ID where to API Registry is located.
    • api_registry_project_id (str): API Registry 所在的 Google Cloud 项目 ID。
  • location (str, optional): The location of to API Registry resources. Defaults to "global".
    • location (str,可选): API Registry 资源的位置。默认为 "global"。
  • header_provider (Callable, optional): A function that takes to call context and returns a dictionary of additional HTTP headers to be sent with requests to to MCP server. This is often used for dynamic authentication or project-specific headers.
    • header_provider (Callable,可选): 接受调用上下文并返回要与对 MCP 服务器的请求一起发送的额外 HTTP 标头字典的函数。这通常用于动态身份验证或特定于项目的标头。

The get_toolset() function has to following configuration options:

get_toolset() 函数具有以下配置选项:

  • mcp_server_name (str): The full name of to registered MCP server from which to load tools, for example: projects/my-project/locations/global/mcpServers/my-server.
    • mcp_server_name (str): 要从中加载工具的已注册 MCP 服务器的完整名称,例如:projects/my-project/locations/global/mcpServers/my-server。
  • tool_filter (Union[ToolPredicate, List[str]], optional): Specifies which tools to include in to toolset.
    • tool_filter (Union[ToolPredicate, List[str]],可选): 指定要在工具集中包含哪些工具。
    • If a list of strings, only tools with names in to list are included.
      • 如果是字符串列表,则仅包含列表中名称的工具。
    • If a ToolPredicate function, to function is called for each tool, and only tools for which it returns to True are included.
      • 如果是 ToolPredicate 函数,则为每个工具调用该函数,并且仅包含返回 True 的工具。
    • If None, all tools from to MCP server are included.
      • 如果为 None,则包含来自 MCP 服务器的所有工具。
  • tool_name_prefix (str, optional): A prefix to add to to name of each tool in to resulting toolset.
    • tool_name_prefix (str,可选): 要添加到结果工具集中每个工具名称的前缀。

Additional resources

其他资源