使用 CX Agent Studio MCP 服务器

CX Agent Studio 提供了一个远程 Model Context Protocol (MCP) 服务器，代理和 AI 应用可以使用该服务器来修改 CX Agent Studio 资源。例如，您可以使用 Gemini CLI 或 Antigravity 来帮助设计和构建 CX Agent Studio 代理应用。

此功能可实现 AI 辅助的开发工作流，大幅减少构建和维护智能体应用的麻烦：

  • Vibe Coding（快速原型设计）：您无需手动点击界面来创建代理，只需告诉 AI 辅助 IDE“创建一个使用 Shopify API 且语气友好的零售支持代理”。编码智能体使用 MCP 服务器为您构建智能体架构。
  • 大规模重构和清理： MCP 服务器擅长在界面中执行繁琐的批量操作。 例如，您可以发出“将所有 15 个子代理中的‘customer_id’参数重命名”或“查找并删除所有未使用的 intent”之类的命令。
  • 交互式评估驱动的开发：您可以运行失败的评估，并指示代理：“修改指令，直到通过此特定评估”。
  • 自我修复和优化：自动化“帮助代理”可以监控代理的性能（例如，未能通过特定评估），并使用 MCP 服务器自主调整指令或修复工具定义，以提高得分（“爬山”算法）。
  • 情境感知：服务器允许编码助理“读取”已部署代理的当前状态，从而让您更轻松地了解复杂的旧版配置，而无需手动浏览 JSON 文件。

限制

存在以下限制：

  • 仅支持 us 区域。
  • 词元上下文限制：大型代理配置（包含许多工具和详尽的指令）在检索完整代理定义时，可能会超出某些编码模型的上下文窗口。建议您提取特定的子组件（例如，仅提取一个工具），而不是一次提取整个应用定义。此外，用户应监控上下文窗口使用情况，并定期（每隔几次请求）重启代理会话以清除缓冲区。
  • 延迟时间：对于小规模更改，“直接突变”（API 调用）通常更快。不过，对于大规模架构重构（重命名 50 个文件中的变量），我们建议使用“导出 -> 本地编辑 -> 导入”工作流来确保数据完整性，MCP 服务器也支持使用 export_app 和 import_app 工具来完成此工作流。

工作原理

服务器公开了 CX Agent Studio API，该 API 也被界面用于构建代理。AI 应用已配置为使用服务器并连接到该服务器。 服务器会宣传可用工具的列表，例如：

  • list_agents()
  • create_tool(name, python_code, ...)
  • update_instruction(agent_name, new_instruction)
  • run_evaluation(dataset)

当您向 AI 应用提供自然语言命令时，AI 应用会决定是否使用 CX Agent Studio MCP 服务器以及要调用哪个工具。

直接突变与本地突变

您可以根据任务的复杂程度使用以下两种不同的工作流程之一：

  • 直接突变（最适合快速开发和原型设计）：将 MCP 服务器直接连接到您的编码环境，以使用 API 调用进行实时更改。
  • 本地副本（最适合大规模使用和控制）：使用 MCP 服务器的 export_app 工具将代理下载到本地文件系统，使用编码助理编辑文件，然后使用 import_app 将更改推送回去。 这对于大规模重构、版本控制集成或合并团队贡献非常有用。

所需的角色

如需获得完成本指南中的任务所需的权限，请让管理员向您授予项目的以下 IAM 角色：

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

在项目中启用 MCP 服务器

如果您使用不同的项目来存储客户端凭证（例如服务账号密钥、OAuth 客户端 ID 或 API 密钥）和托管资源，则必须在两个项目中都启用 ces.googleapis.com 服务和 MCP 服务器。

如需在 Google Cloud 项目中启用服务器，请运行以下命令：

gcloud beta services mcp enable ces.googleapis.com \
    --project=PROJECT_ID

在项目中停用 MCP 服务器

如需在项目中停用 MCP 服务器，请运行以下命令：

gcloud beta services mcp disable ces.googleapis.com \
    --project=PROJECT_ID

身份验证和授权

Google Cloud MCP 服务器使用 OAuth 2.0 协议和 Identity and Access Management (IAM) 进行身份验证和授权。支持所有 Google Cloud 身份用于向 MCP 服务器进行身份验证。

我们建议您为使用 MCP 工具的客服人员创建单独的身份，以便控制和监控对资源的访问权限。如需详细了解身份验证，请参阅向 MCP 服务器进行身份验证。

MCP OAuth 范围

OAuth 2.0 使用范围和凭证来确定经过身份验证的主账号是否有权对资源执行特定操作。如需详细了解 Google 的 OAuth 2.0 范围，请参阅使用 OAuth 2.0 访问 Google API。

CX Agent Studio 具有以下 MCP 工具 OAuth 范围： https://www.googleapis.com/auth/ces

配置 MCP 客户端以使用 CES MCP 服务器

Claude 或 Gemini CLI 等 AI 应用和代理可以实例化连接到单个 MCP 服务器的 MCP 客户端。AI 应用可以有多个连接到不同 MCP 服务器的客户端。如需连接到远程 MCP 服务器，MCP 客户端必须知道远程 MCP 服务器的网址。

在 AI 应用中，寻找连接到远程 MCP 服务器的方式。系统会提示您输入服务器的详细信息，例如名称和网址。

对于 CX Agent Studio MCP 服务器，请根据需要输入以下内容：

  • 服务器名称：CES MCP 服务器
  • 服务器网址或端点：https://ces.us.rep.googleapis.com/mcp
  • 传输：HTTP
  • 身份验证详细信息：您的 Google Cloud 凭证、您的 OAuth 客户端 ID 和密钥，或代理身份和凭证。 您选择的身份验证详细信息取决于您想要如何进行身份验证。 如需了解详情，请参阅向 MCP 服务器进行身份验证。

如需查看有关设置和连接到 MCP 服务器的特定于主机的指导，请参阅以下内容：

如需更一般的指导，请参阅以下资源：

可用的工具

如需查看 Customer Experience Agent Studio MCP 服务器的可用 MCP 工具的详细信息及其说明，请参阅 Customer Experience Agent Studio MCP 参考文档。

列出工具

使用 MCP 检查器列出工具，或直接向 Customer Experience Agent Studio 远程 MCP 服务器发送 tools/list HTTP 请求。tools/list 方法不需要进行身份验证。

POST /mcp HTTP/1.1
Host: ces.googleapis.com
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/list",
}

可选的安全配置

由于 MCP 工具可执行各种操作，因此 MCP 会引发新的安全风险和注意事项。为了最大限度地降低这些风险并进行管理，Google Cloud 提供了默认设置和可自定义的政策，用于控制 MCP 工具在 Google Cloud组织或项目中的使用。

如需详细了解 MCP 安全性和治理，请参阅 AI 安全性。

使用 Model Armor

Model Armor 是一项Google Cloud 服务，旨在增强 AI 应用的安防和安全性。它通过主动筛选 LLM 提示和回答来防范各种风险，并支持 Responsible AI 实践。无论您是在云环境还是外部云服务提供商中部署 AI，Model Armor 都能帮助您防止恶意输入、验证内容安全性、保护敏感数据、保持合规性，并在各种 AI 环境中以一致的方式实施 AI 安全政策。

Model Armor 仅在特定区域位置提供。如果为项目启用了 Model Armor，并且对该项目的调用来自不受支持的区域，则 Model Armor 会进行跨区域调用。 如需了解详情，请参阅 Model Armor 位置。

启用 Model Armor

您必须先启用 Model Armor API，然后才能使用 Model Armor。

控制台

  1. Enable the Model Armor API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  2. 选择要启用 Model Armor 的项目。

gcloud

在开始之前，请使用 Google Cloud CLI 和 Model Armor API 按照以下步骤操作：

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. 运行以下命令，为 Model Armor 服务设置 API 端点。

    gcloud config set api_endpoint_overrides/modelarmor "https://modelarmor.LOCATION.rep.googleapis.com/"

    将 LOCATION 替换为您要使用 Model Armor 的区域。

    3. 为 Google 和 Google Cloud 远程 MCP 服务器配置保护

    为了保护您的 MCP 工具调用和响应，您需要创建 Model Armor 下限设置，然后为项目启用 MCP 内容安全功能。基准设置用于定义适用于整个项目的最低安全过滤条件。此配置会对项目中的所有 MCP 工具调用和响应应用一组一致的过滤条件。

    1. 设置启用了 MCP 清理功能的 Model Armor 下限设置。如需了解详情，请参阅配置 Model Armor 底价设置。

      请参阅以下示例命令：

      gcloud model-armor floorsettings update \
--full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
--enable-floor-setting-enforcement=TRUE \
--add-integrated-services=GOOGLE_MCP_SERVER \
--google-mcp-server-enforcement-type=INSPECT_AND_BLOCK \
--enable-google-mcp-server-cloud-logging \
--malicious-uri-filter-settings-enforcement=ENABLED \
--add-rai-settings-filters='[{"confidenceLevel": "HIGH", "filterType": "DANGEROUS"}]'

      将 PROJECT_ID 替换为您的 Google Cloud 项目 ID。

      请注意以下设置：

      • INSPECT_AND_BLOCK：用于检查 Google MCP 服务器的内容并屏蔽与过滤条件匹配的提示和回答的强制执行类型。
      • ENABLED：用于启用过滤或强制执行的设置。
      • HIGH：Responsible AI - Dangerous 过滤设置的置信度。您可以修改此设置，但较低的值可能会导致更多假正例。如需了解详情，请参阅配置下限设置。

    2. 为您的项目启用针对远程 MCP 服务器的 Model Armor 保护。

      gcloud beta services mcp content-security add modelarmor.googleapis.com --project=PROJECT_ID

      将 PROJECT_ID 替换为您的 Google Cloud项目 ID。运行此命令后，Model Armor 会清理项目中的所有 MCP 工具调用和响应，无论这些调用和响应来自何处。

    3. 如需确认 Google MCP 流量是否已发送到 Model Armor，请运行以下命令：

      gcloud beta services mcp content-security get --project=PROJECT_ID

      将 PROJECT_ID 替换为 Google Cloud 项目 ID。

    禁止使用 Model Armor 扫描 MCP 流量

    如果您想在项目中使用 Model Armor，但又想停止使用 Model Armor 扫描 Google MCP 流量，请运行以下命令：

    gcloud model-armor floorsettings update \
  --full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
  --remove-integrated-services=GOOGLE_MCP_SERVER

    将 PROJECT_ID 替换为 Google Cloud 项目 ID。

    Model Armor 不会扫描项目中的 MCP 流量。

    使用 IAM 拒绝政策控制 MCP 使用情况

    Identity and Access Management (IAM) 拒绝政策有助于保护 Google Cloud 远程 MCP 服务器。配置这些政策以阻止不需要的 MCP 工具访问。

    例如，您可以根据以下条件拒绝或允许访问：

    • 正文。
    • 工具属性，例如只读。
    • 应用的 OAuth 客户端 ID。

    如需了解详情，请参阅使用 Identity and Access Management 控制 MCP 使用情况。

    后续步骤