Testar, depurar e avaliar no Modo de Desenvolvedor dos apps do Gemini

Use o Modo de Desenvolvedor dos apps do Gemini para testar de forma interativa seu servidor do Protocolo de Contexto de Modelo (MCP), diagnosticar erros de esquema ou de tempo de execução e avaliar a qualidade da ferramenta antes de enviar seu app conectado para análise no Google Connected Console.

Este guia aborda as seguintes tarefas:

  • Ativar o Modo de Desenvolvedor dos apps do Gemini no Gemini, criar um app MCP personalizado e verificar a descoberta inicial de ferramentas.
  • Depurar chamadas de ferramentas com falha, sincronizar esquemas atualizados e testar a autenticação.
  • Simular o contexto do ambiente do usuário e configurar a autenticação do cliente.

Para uma introdução ao layout do espaço de trabalho e às guias do inspetor, consulte a visão geral do Modo de Desenvolvedor dos apps do Gemini.

Ativar o Modo de Desenvolvedor dos apps do Gemini

Se você estiver integrando seu servidor MCP no Google Connected Console, seu app registrado já estará disponível quando você ativar o Modo Desenvolvedor dos apps do Gemini, e poderá pular a Etapa 2. Se você quiser testar um endpoint de servidor MCP HTTPS implantado diretamente no Gemini antes de registrá-lo no console, siga as duas etapas para ativar o Modo de Desenvolvedor dos apps do Gemini e conectar seu servidor como um app MCP personalizado.

Etapa 1: ativar o Modo de Desenvolvedor dos apps do Gemini

  1. Abra o Gemini no navegador da Web.
  2. Clique em Configurações > Modo de Desenvolvedor dos apps do Gemini ou acesse diretamente gemini.google.com/devmode.

(Opcional) Etapa 2: criar e testar um app MCP personalizado

Para conectar seu servidor MCP como um app personalizado no Modo de Desenvolvedor dos apps do Gemini, faça o seguinte:

  1. Na caixa de diálogo Escolher um app, clique em + Criar novo.
  2. Na caixa de diálogo Conectar a um servidor MCP, insira o endpoint HTTPS público do seu servidor em URL do servidor MCP. Verifique se o URL começa com https://, por exemplo, https://your-app-link.com/mcp.
  3. Se o servidor exigir credenciais OAuth pré-registradas, clique em Configurações adicionais > Mostrar mais para inserir o ID do cliente OAuth e a chave secreta do cliente e clique em Próxima.
  4. Na caixa de diálogo de confirmação de segurança e privacidade, confira como o Gemini interage com seu servidor MCP personalizado:
    • Execução de ferramentas: o Gemini executa as ferramentas do servidor MCP para acionar e executar funções disponíveis para processar suas solicitações.
    • Recuperação e compartilhamento de dados: o Gemini recupera e gerencia recursos, esquemas e contextos expostos pelos endpoints do seu servidor MCP e pode compartilhar informações às quais tem acesso com base nas configurações da sua Conta do Google ou ao interagir com outros apps conectados.
    • Confiança e desconexão: verifique se o servidor MCP é confiável e leia a Política de Privacidade dele antes de continuar. Você pode desconectar o servidor a qualquer momento na página "Apps conectados" ou excluir o link dele nas conexões da sua Conta do Google.
  5. Selecione Entendo e aceito os riscos de segurança e privacidade ao conectar este app personalizado. Em seguida, clique em Conectar.
  6. Na caixa de diálogo Salvar seu app personalizado, insira um nome de exibição para o app, verifique se as ferramentas do servidor aparecem na lista Ações disponíveis e clique em Conectar.
  7. No painel lateral do Modo de Desenvolvedor dos apps do Gemini, selecione a guia Esquemas de ferramentas para conferir informações sobre cada ferramenta no app conectado, incluindo definições de parâmetros, selos de segurança (Somente leitura, Destrutivo, Autenticação necessária), Esquema bruto e Estrutura de resposta.
  8. No painel de chat à esquerda, insira comandos em linguagem natural ou @mention (por exemplo, @MyApp show my profile) e monitore a guia log de eventos para ver como a ferramenta está funcionando.

Depurar chamadas de ferramentas

Quando uma chamada de ferramenta falha ou produz argumentos inesperados, é possível inspecionar a telemetria de diagnóstico, atualizar o servidor MCP de back-end e recarregar o esquema sem limpar o histórico de conversas.

Para depurar uma chamada de ferramenta com falha, faça o seguinte:

  1. No painel direito, selecione a guia Log de Eventos.
  2. Clique no evento com falha na lista Telemetria para abrir os detalhes e inspecionar o payload da solicitação Tool call e a resposta Tool result:
    • Erros de conexão e de rede: verifique as mensagens de erro e a latência para confirmar se o endpoint está acessível.
    • Erros de autenticação: se o evento retornar 401 ou 403, verifique o estado do token OAuth ou as credenciais do cliente na guia Autenticação.
    • Incompatibilidades de validação de esquema: se o servidor retornar um erro de parâmetros inválidos do MCP (-32602), compare os argumentos JSON gerados pelo modelo em Tool call com os tipos de parâmetro, as propriedades obrigatórias e as instruções de formato na guia Esquemas de ferramentas.
    • Exceções de ambiente de execução do servidor: inspecione o código do erro e a mensagem JSON-RPC em Tool result para diagnosticar exceções de back-end.
  3. Para resolver o problema, atualize a implementação do servidor MCP ou refine as descrições de ferramentas e parâmetros. Para orientações sobre como escrever esquemas de ferramentas e respostas de erro claros, consulte Padrões de integração de apps conectados ao MCP.
  4. Na guia Esquemas de ferramentas, clique em Sincronizar esquema. O Gemini busca novamente tools/list do seu servidor MCP e atualiza as definições de ferramentas ativas, preservando a conversa atual.
  5. Tente refazer a consulta. Na guia log de eventos, confirme se a chamada de ferramenta reproduzida retorna 200 OK e renderiza a resposta esperada na prévia do chat.

Simular o contexto e a autenticação do ambiente

É possível testar como as ferramentas do MCP respondem a diferentes locais, fusos horários, localidades e métodos de autenticação do usuário diretamente no painel do inspetor.

Substituir o contexto do ambiente

Para simular o contexto do usuário para ferramentas que dependem de data, hora ou localidade, faça o seguinte:

  1. No painel direito, selecione a guia Environment.
  2. Em Data e hora, selecione uma Data simulada e uma Hora simulada para testar expressões de tempo relativas (como "amanhã de manhã" ou "este sábado à tarde").
  3. Em Preferências, selecione um Idioma para simular a localidade do usuário (por exemplo, en-US).
  4. Execute um comando de teste no painel de conversa para avaliar sua ferramenta com o contexto simulado.
  5. Para restaurar as configurações padrão do ambiente, clique em Redefinir.

Configurar a autenticação do cliente

Para configurar ou mudar o método de autenticação usado durante a sessão do Modo de Desenvolvedor dos apps do Gemini, faça o seguinte:

  1. No painel direito, selecione a guia Authentication.
  2. Em Configuração de autenticação do cliente, selecione um dos seguintes modos de autenticação:
    • Registro dinâmico de clientes: usa um fluxo do OAuth para negociar credenciais automaticamente com o servidor de autorização. Para mais informações, consulte o guia de implementação do OAuth 2.1. Se aplicável, insira seu endpoint em Adicionar um link de app personalizado.
    • Registro manual do cliente: permite que você forneça manualmente um ID e uma chave secreta do cliente pré-registrados. Expanda Configurações avançadas para definir outras substituições de fluxo.
  3. Clique em Salvar e aguarde a mensagem Salvo aparecer. Em seguida, execute um comando de teste para verificar se as ferramentas autenticadas funcionam.

Outros recursos