Usar o servidor MCP do CX Agent Studio

O CX Agent Studio oferece um servidor Protocolo de Contexto de Modelo (MCP) remoto que pode ser usado por agentes e aplicativos de IA para editar recursos do CX Agent Studio. Por exemplo, você pode usar a CLI do Gemini ou o Antigravity para ajudar a projetar e criar seu aplicativo de agente do CX Agent Studio.

Esse recurso permite fluxos de trabalho de desenvolvimento assistidos por IA, reduzindo drasticamente o atrito da criação e da manutenção de aplicativos de agente:

  • Vibe Coding (prototipagem rápida): em vez de clicar manualmente na UI para criar um agente, basta dizer ao seu ambiente de desenvolvimento integrado com tecnologia de IA "Crie um agente de suporte ao varejo que use a API do Shopify e fale em um tom amigável". O agente de programação usa o servidor MCP para construir a arquitetura do agente.
  • Refatoração e limpeza em massa:o servidor MCP é excelente em operações em massa que são tediosas em uma UI. Por exemplo, você pode comandar "Renomeie o parâmetro 'customer_id' em todos os 15 subagentes" ou "Encontre e exclua todas as intents não usadas".
  • Desenvolvimento interativo orientado por avaliação:é possível executar uma avaliação com falha e instruir o agente: "Modifique as instruções até que essa avaliação específica seja aprovada".
  • Autocorreção e otimização:um "agente auxiliar" automatizado pode monitorar a performance de um agente (por exemplo, reprovação em uma avaliação específica) e usar o servidor MCP para ajustar autonomamente as instruções ou corrigir as definições de ferramentas para melhorar a pontuação ("Hill Climbing").
  • Percepção contextual:o servidor permite que os assistentes de programação "leiam" o estado atual de um agente implantado, facilitando a compreensão de configurações legadas complexas sem precisar analisar arquivos JSON manualmente.

Limitações

Considere as seguintes limitações:

  • Somente a região us é compatível.
  • Limites de contexto de token:configurações de agentes grandes (com muitas ferramentas e instruções extensas) podem exceder a janela de contexto de alguns modelos de programação ao recuperar definições completas de agentes. Recomendamos buscar subcomponentes específicos (por exemplo, apenas uma ferramenta) em vez da definição completa do app de uma só vez. Além disso, os usuários precisam monitorar o uso da janela de contexto e reiniciar a sessão do agente periodicamente (a cada poucos pedidos) para limpar o buffer.
  • Latência:as mutações diretas (chamadas de API) geralmente são mais rápidas para pequenas mudanças. No entanto, para refatorações arquitetônicas massivas (renomear variáveis em 50 arquivos), recomendamos o fluxo de trabalho "Exportar -> Editar localmente -> Importar" para garantir a integridade dos dados. O servidor MCP também oferece suporte a esse fluxo usando as ferramentas export_app e import_app.

Como funciona

O servidor expõe a API CX Agent Studio, que também é usada pela UI para criar agentes. Seu aplicativo de IA está configurado para usar o servidor e se conectar a ele. O servidor anuncia uma lista de ferramentas disponíveis, como:

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

Quando você dá um comando em linguagem natural para seu aplicativo de IA, ele decide se vai usar o servidor do MCP do CX Agent Studio e qual ferramenta chamar.

Mutações diretas x locais

É possível usar um de dois fluxos de trabalho distintos dependendo da complexidade da tarefa:

  • Mutação direta (melhor para velocidade e prototipagem): conecte o servidor MCP diretamente ao seu ambiente de programação para fazer mudanças em tempo real usando chamadas de API.
  • Cópias locais (melhor para escalonamento e controle): use a ferramenta export_app do servidor MCP para fazer o download do agente no sistema de arquivos local, edite os arquivos com seu assistente de programação e envie as mudanças de volta usando import_app. Isso é útil para refatoração em grande escala, integração de controle de versão ou fusão de contribuições da equipe.

Funções exigidas

Para conseguir as permissões necessárias a fim de concluir as tarefas neste guia, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Ativar o servidor MCP em um projeto

Se você estiver usando projetos diferentes para suas credenciais de cliente, como chaves de conta de serviço, ID do cliente OAuth ou chaves de API, e para hospedar seus recursos, será necessário ativar o serviço ces.googleapis.com e o servidor MCP nos dois projetos.

Para ativar o servidor no seu projeto Google Cloud , execute o seguinte comando:

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

Desativar o servidor MCP em um projeto

Para desativar o servidor MCP no seu projeto, execute o seguinte comando:

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

Autenticação e autorização

Os servidores do MCP no Google Cloud usam o protocolo OAuth 2.0 com o Identity and Access Management (IAM) para autenticação e autorização. Todas as Google Cloud identidades são compatíveis com a autenticação em servidores MCP.

Recomendamos que você crie uma identidade separada para agentes que usam ferramentas do MCP para que o acesso aos recursos possa ser controlado e monitorado. Para mais informações sobre autenticação, consulte Autenticar em servidores do MCP.

Escopos OAuth do MCP

O OAuth 2.0 usa escopos e credenciais para determinar se um principal autenticado está autorizado a realizar uma ação específica em um recurso. Para mais informações sobre os escopos do OAuth 2.0 no Google, leia Como usar o OAuth 2.0 para acessar as APIs do Google.

O CX Agent Studio tem os seguintes escopos do OAuth da ferramenta MCP: https://www.googleapis.com/auth/ces

Configurar um cliente MCP para usar o servidor MCP do CES

Aplicativos e agentes de IA, como a CLI do Claude ou do Gemini, podem instanciar um cliente do MCP que se conecta a um único servidor do MCP. Um aplicativo de IA pode ter vários clientes que se conectam a diferentes servidores do MCP. Para se conectar a um servidor MCP remoto, o cliente MCP precisa saber o URL dele.

No seu aplicativo de IA, procure uma maneira de se conectar a um servidor MCP remoto. Você precisa inserir detalhes sobre o servidor, como nome e URL.

Para o servidor MCP do CX Agent Studio, insira o seguinte conforme necessário:

  • Nome do servidor: servidor MCP do CES
  • URL do servidor ou Endpoint: https://ces.us.rep.googleapis.com/mcp
  • Transporte: HTTP
  • Detalhes de autenticação: suas credenciais Google Cloud , seu ID e chave secreta do cliente OAuth ou uma identidade e credenciais do agente. Os detalhes de autenticação que você escolhe dependem de como você quer se autenticar. Para mais informações, consulte Autenticar em servidores do MCP.

Para orientações específicas do host sobre como configurar e se conectar ao servidor MCP, consulte o seguinte:

Para orientações mais gerais, consulte os seguintes recursos:

Ferramentas disponíveis

Para conferir detalhes das ferramentas do MCP disponíveis e as descrições delas para o servidor MCP do Customer Experience Agent Studio, consulte a referência do MCP do Customer Experience Agent Studio.

Ferramentas de lista

Use o inspetor do MCP para listar ferramentas ou envie uma solicitação HTTP tools/list diretamente ao servidor MCP remoto do Customer Experience Agent Studio. O método tools/list não requer autenticação.

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

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

Configurações opcionais de segurança

A MCP apresenta novos riscos e considerações de segurança devido à grande variedade de ações que podem ser realizadas com as ferramentas dela. Para minimizar e gerenciar esses riscos, o Google Cloud oferece configurações padrão e políticas personalizáveis para controlar o uso de ferramentas de MCP na sua organização ou projeto do Google Cloud.

Para mais informações sobre segurança e governança do MCP, consulte Segurança e proteção de IA.

Usar o Model Armor

O Model Armor é um Google Cloud serviço projetado para aumentar a segurança dos seus aplicativos de IA. Ele funciona examinando de forma proativa comandos e respostas de LLMs, protegendo contra vários riscos e apoiando práticas de IA responsável. Se você implanta a IA no seu ambiente de nuvem ou em provedores de nuvem externos, o Model Armor pode ajudar a evitar entradas maliciosas, verificar a segurança do conteúdo, proteger dados sensíveis, manter a conformidade e aplicar suas políticas de segurança e proteção de IA de maneira consistente em todo o seu cenário diversificado de IA.

O Model Armor está disponível apenas em locais regionais específicos. Se o Model Armor estiver ativado para um projeto e uma chamada para esse projeto vier de uma região sem suporte, o Model Armor fará uma chamada entre regiões. Para mais informações, consulte Locais do Model Armor.

Ativar o Model Armor

É necessário ativar as APIs do Model Armor antes de usar o Model Armor.

Console

  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. Selecione o projeto em que você quer ativar o Model Armor.

gcloud

Antes de começar, siga estas etapas usando a Google Cloud CLI com a API Model Armor:

  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. Execute o comando a seguir para definir o endpoint de API do serviço Model Armor.

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

    Substitua LOCATION pela região em que você quer usar o Model Armor.

    3. Configurar a proteção para servidores MCP remotos e do Google Google Cloud

    Para proteger as chamadas e respostas de ferramentas do MCP, crie uma configuração de restrição do Model Armor e ative a segurança de conteúdo do MCP para seu projeto. Uma configuração mínima define os filtros de segurança mínimos que se aplicam a todo o projeto. Essa configuração aplica um conjunto consistente de filtros a todas as chamadas e respostas de ferramentas do MCP no projeto.

    1. Configure uma configuração de valor mínimo do Model Armor com a limpeza do MCP ativada. Para mais informações, consulte Configurar configurações mínimas do Model Armor.

      Confira o exemplo de comando a seguir:

      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"}]'

      Substitua PROJECT_ID pelo Google Cloud ID do projeto.

      Observe as seguintes configurações:

      • INSPECT_AND_BLOCK: o tipo de aplicação que inspeciona o conteúdo do servidor MCP do Google e bloqueia solicitações e respostas que correspondem aos filtros.
      • ENABLED: a configuração que ativa um filtro ou aplicação.
      • HIGH: o nível de confiança para as configurações do filtro de IA responsável - perigoso. É possível modificar essa configuração, mas valores mais baixos podem resultar em mais falsos positivos. Para mais informações, consulte Configurar opções de piso.

    2. No seu projeto, ative a proteção do Model Armor para servidores MCP remotos.

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

      Substitua PROJECT_ID pelo ID do projeto do Google Cloud. Depois de executar esse comando, o Model Armor higieniza todas as chamadas de ferramentas e respostas do MCP no projeto, independentemente de onde elas se originam.

    3. Para confirmar se o tráfego do Google MCP está sendo enviado para o Model Armor, execute o seguinte comando:

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

      Substitua PROJECT_ID pelo ID do projeto Google Cloud .

    Desativar a verificação do tráfego do MCP com o Model Armor

    Se você quiser usar o Model Armor em um projeto e parar de verificar o tráfego do Google MCP com o Model Armor, execute o seguinte comando:

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

    Substitua PROJECT_ID pelo Google Cloud ID do projeto.

    O Model Armor não vai verificar o tráfego do MCP no projeto.

    Controlar o uso do MCP com políticas de negação do IAM

    As políticas de negação do Identity and Access Management (IAM) ajudam a proteger Google Cloud servidores MCP remotos. Configure essas políticas para bloquear o acesso indesejado à ferramenta MCP.

    Por exemplo, é possível negar ou permitir o acesso com base em:

    • O principal.
    • Propriedades da ferramenta, como somente leitura.
    • O ID do cliente OAuth do aplicativo.

    Para mais informações, consulte Controlar o uso do MCP com o Identity and Access Management.

    A seguir