Guia para desenvolvedores do servidor MCP da Connected Apps Platform

Os apps conectados ajudam os usuários a acessar conteúdo e serviços em uma ampla variedade de jornadas, nos produtos do Google aplicáveis.

Os apps conectados oferecem os seguintes benefícios.

  • Controle sobre quais recursos e serviços disponibilizar para a Connected Apps Platform: você mantém o controle granular sobre o escopo de integração.
  • Atribuição e descoberta de marca: quando você seleciona uma plataforma do Google para integrar ao seu app, sua marca fica em destaque.
  • Maior potencial de engajamento: os apps conectados ajudam os usuários a acessar seu serviço para realizar ações quando necessário, aumentando a probabilidade de maior engajamento e satisfação do usuário.

Opções de integrações

Um servidor MCP e as AppFunctions são as duas maneiras principais e complementares de integrar os recursos do seu app aos produtos do Google aplicáveis.

  • Servidor MCP (descrito neste guia para desenvolvedores):

    • Esse é o caminho padrão recomendado para recursos básicos multiplataforma.
    • O servidor MCP permite que você faça o escalonamento no Android, iOS e na Web. Se você tiver APIs da Web ou um servidor MCP remoto, poderá usá-los com nossa especificação de servidor MCP. Esse é o caminho para o alcance máximo com o mínimo de sobrecarga.

  • MCP do Android (guia para desenvolvedores)

    • As AppFunctions foram criadas para criar experiências mais profundas e integradas no Android. As AppFunctions podem aproveitar o conteúdo no dispositivo para resolver intents usando a integração profunda com o SO Android e as plataformas da interface do sistema.
    • Ações que exigem contexto e integração total com o estado atual de um app.
    • O suporte está disponível em uma biblioteca do Jetpack.

Processo de ponta a ponta

Este guia descreve o processo completo para criar, testar, registrar e implantar um servidor remoto do Protocolo de Contexto de Modelo (MCP) para integrar seus serviços aos produtos do Google aplicáveis.

Fase 1: criação — desenvolver o servidor MCP remoto

Ao desenvolver um servidor MCP remoto usando a especificação do Protocolo de Contexto de Modelo, recomendamos estabelecer instruções de sistema estruturadas, anotações de segurança explícitas, definições de esquema claras e vinculações de metadados de interface.

  • Instruções explícitas do servidor: ao inicializar o servidor MCP, defina instruções claras que descrevam seu domínio e recursos. Como os modelos de IA dependem dessas instruções do servidor para reconhecer quando delegar tarefas ao servidor, recomendamos fornecer instruções claras do servidor para facilitar o roteamento de modelos preciso em todos os produtos do Google aplicáveis.
  • Anotações de ferramentas de segurança e execução: declare anotações de protocolo explícitas para cada ferramenta, como marcar operações de consulta somente leitura com readOnlyHint=True ou ações destrutivas/de mudança de estado com destructiveHint=True. Também é possível marcar operações que exigem confirmações no Google Connected Console.
  • Esquemas com tipos bem definidos e docstrings semânticas: forneça tipos de argumentos explícitos e docstrings de parâmetros detalhadas. Documente os valores de campo esperados com clareza (como filtros de filtragem de categoria permitidos ou parâmetros de localização) para otimizar a precisão da chamada de ferramentas do modelo.
  • Vinculações de metadados de recursos de interface (opcional): vincule as saídas da ferramenta diretamente a recursos de interface personalizados definindo anotações de metadados (por exemplo, meta={"ui": {"resourceUri": "ui://..."}}). Se fornecido, isso instrui o cliente a renderizar widgets de interface interativos, avançados e com marca em iframes seguros em sandbox diretamente na interface de conversação.

Fase 2: validar — testar localmente com o MCP Inspector

Antes de hospedar seu serviço remotamente, valide as declarações de ferramentas e a renderização da interface em um ambiente de sandbox local.

  • Inicialização do servidor local: execute o servidor MCP remoto localmente na sua máquina de desenvolvimento.
  • Validação da ferramenta Inspector: conecte-se ao servidor local usando a ferramenta MCP Inspector (npx @modelcontextprotocol/inspector).
  • Execução e verificação da interface: invoque ferramentas individuais, inspecione payloads de entrada/saída JSON brutos e confirme se os recursos de interface personalizados são renderizados conforme o esperado diretamente no navegador da Web.

Fase 3: implantar e testar com o modo de desenvolvedor do Gemini

É necessário implantar o servidor MCP em um endpoint HTTPS público para disponibilizá-lo remotamente para testes no Modo de Desenvolvimento do Gemini. É possível hospedá-lo em qualquer provedor de nuvem ou infraestrutura que você preferir.

A próxima etapa é validar o endpoint público no Modo de Desenvolvedor do Gemini.

  • Verificação do Gemini Live: teste a execução de ferramentas em tempo real usando o Modo de Desenvolvedor do Gemini. Use as guias de depuração integradas, incluindo o log de eventos, os esquemas de ferramentas, a simulação de ambiente (data, hora, local) e as configurações de autenticação, para verificar as respostas do modelo antes de solicitar a aprovação final e publicar.

Fase 4: registro — configurar usando o Google Connected Console

Depois de validar a execução local, envie sua solicitação de acesso e registre os detalhes da integração no Google Connected Console.

  • Solicitação de acesso: peça acesso usando o formulário de interesse.
  • Configuração e publicação do console: no Google Connected Console, defina os detalhes do app, configure a autenticação e os endpoints, descubra ferramentas, gerencie ambientes de pré-lançamento e testadores e envie o aplicativo para revisão e publicação. Leia o guia.