Solucionar problemas de aplicativos MCP no Microsoft 365 Copilot

Este guia fornece conselhos de solução de problemas comuns que você pode encontrar ao desenvolver um aplicativo MCP (Protocolo de Contexto de Modelo) para integração com um agente declarativo dentro do Microsoft 365 Copilot.

Habilitar o modo de desenvolvedor

A ativação do modo de desenvolvedor mostra logs e erros nas respostas do agente. Essas informações são essenciais para depuração. Para habilitar o modo de desenvolvedor, digite o comando a seguir no Microsoft Copilot.

-developer on

As ferramentas MCP disponíveis para seu agente aparecem na seção Ações do card de informações de depuração. Para obter detalhes sobre o card de informações de depuração, consulte Usar o modo de desenvolvedor no Microsoft 365 Copilot para testar e depurar agentes.

Problemas de descoberta e entrada

Nenhuma ferramenta listada

Se a seção Ações do card de informações de depuração não listar nenhuma ferramenta MCP, marque os itens a seguir.

  • Confirme se o servidor MCP está em execução e se você está se conectando ao ponto de extremidade MCP correto no manifesto do plug-in.
  • Verifique se o manifesto do plug-in inclui as ferramentas esperadas na functions propriedade.
  • Verifique se o tempo de execução do servidor MCP especificado na propriedade no manifesto runtimes do plug-in:
    • Faz referência às mcp_tool_description ferramentas na propriedade:
      • Referenciar um arquivo JSON que contém as descrições da ferramenta na file propriedade OU
      • Listar as descrições embutidas da tools ferramenta na propriedade
    • Inclui os nomes de ferramenta na run_for_functions propriedade.
"runtimes": [
  {
    "type": "RemoteMCPServer",
    "spec": {
      "url": "https://api.contoso.com/mcp",
      "mcp_tool_description": "mcp-tools.json"
    },
    "run_for_functions": [
      "get_widget",
      "create_widget"
    ]
  }
]

Ferramentas não acionadas a partir do chat do Copilot

  • Reveja as descrições de ferramentas e parâmetros para garantir que forneçam contexto suficiente. Considere reescrevê-los usando "Usar esta função/parâmetro quando..." fraseado.
  • Mantenha as descrições com menos de 1.024 caracteres. Texto com mais de 1.024 caracteres será ignorado.
  • Certifique-se de que a visibilidade da ferramenta esteja definida corretamente.
    • Para aplicativos MCP, _meta.ui.visibility inclui model.
    • Para aplicativos SDK do OpenAI, meta["openai/visibility"] é definido como public.

A ferramenta errada está selecionada

  • Evite ferramentas com nomes semelhantes ou descrições sobrepostas.
  • Adicione diferenciais claros nas descrições que explicam quando cada ferramenta deve ser usada.

Problemas com widgets

O widget não renderiza

Se a ferramenta MCP correta for chamada, mas o widget de interface do usuário não for renderizado na resposta, o servidor MCP provavelmente retornará apenas conteúdo estruturado sem componente de interface do usuário. Verifique se a associação da interface do usuário está configurada corretamente.

  • Para aplicativos MCP, a definição da ferramenta inclui _meta.ui.resourceUri definido como um recurso HTML registrado com o tipo text/html;profile=mcp-appMIME.
  • Para aplicativos OpenAI SDK, a definição da ferramenta inclui _meta["openai/outputTemplate"] definir um recurso HTML registrado com o tipo text/html+skybridgeMIME.

Falha ao carregar o widget

  • Abra as ferramentas de desenvolvedor do navegador e marque se há violações da Política de Segurança de Conteúdo (CSP) no console. Certifique-se de que as solicitações da URL do host do widget estejam listadas na lista de permissões. Para obter mais informações, consulte Requisitos do servidor MCP para aplicativos MCP.
  • Verifique se o widget compila todas as dependências de HTML e JavaScript em um único arquivo sem ativos externos não resolvidos.

O widget é carregado sem dados

  • Verifique a estrutura de resposta da ferramenta.
    • content deve conter apenas os dados (modelo).
    • structuredContent deve conter os dados e o widget.
    • _meta deve conter apenas o widget.
  • Garantir structuredContent ou _meta incluir os dados necessários.

O widget tem uma barra de rolagem dupla

O contêiner de host do Copilot já tem um scroll com altura máxima. Desative a rolagem interna em seu widget definindo overflow: hidden em seus estilos de contêiner.

Tags <a> âncora não funcionam para links externos no Copilot. Em vez disso, use as APIs de plataforma apropriadas.

  • Para aplicativos MCP, use app.openLink.
  • Para aplicativos SDK do OpenAI, use window.openai.openExternal.

A tela inteira não funciona em alguns hosts Copilot

A exibição em tela inteira não é compatível com todos os hosts do Copilot. Como prática recomendada, sempre marque os recursos do host e exiba condicionalmente os elementos da interface do usuário (como um botão de tela inteira). Para obter mais informações, consulte Verificar disponibilidade da API.

Problemas de resposta

Problemas de expiração do resultado da ferramenta

Certifique-se de que as respostas da ferramenta sejam enviadas ou contentstructuredContent não sejam excessivamente grandes. Se o widget exigir metadados avançados que não são úteis para o modelo, como URLs de avatar ou detalhes específicos da interface do usuário, inclua os dados completos e _meta forneça um resumo conciso no contentformato . Essa abordagem garante que o modelo retenha informações importantes, ao mesmo tempo em que oferece suporte a uma experiência eficaz de várias voltas.

Dados duplicados no widget e resumo de texto

Resolva esse problema usando uma das seguintes opções:

  • Otimize a separação de dados: use _meta para dados específicos de widgets e content para resumos visíveis ao modelo.
  • Formatação de direção: use instruções no manifesto do agente declarativo para orientar como as respostas são estruturadas e apresentadas.

Problemas de autenticação

Incompatibilidade da ID do aplicativo entre a configuração de autenticação e o plug-in

Se você vir erros no seu card de informações de depuração semelhantes a:

OAuth authentication failed: The App ID used in the request does not match the App ID in the authentication configuration. (HTTP 404)

Acesse o portal do desenvolvedor do Teams. Localize o registro do cliente OAuth ou do cliente de logon único (SSO) e verifique se a ID do aplicativo em seu plug-in corresponde à ID do aplicativo registrada.

A URL base na configuração de autenticação não corresponde ao plug-in

Se você vir erros no seu card de informações de depuração semelhantes a:

OAuth authentication failed: The base URL in your authentication configuration does not match the server URL. (HTTP 401)

Acesse o portal do desenvolvedor do Teams. Localize o registro do cliente OAuth ou do cliente SSO e verifique se o URL do servidor MCP no plug-in corresponde ao URL base registrado.

A ID de referência no manifesto do plug-in está incorreta ou ausente

Se você vir erros no seu card de informações de depuração semelhantes a:

OAuth authentication failed: No matching configuration found for referenceID in 'runtime.auth' section of the action manifest

Acesse o portal do desenvolvedor do Teams. Encontre o registro do cliente OAuth ou do cliente SSO e verifique se a ID no tempo de execução auth.reference_id do servidor MCP corresponde à ID do registro no portal do desenvolvedor.

A política da organização restringe o acesso

Se você vir erros no seu card de informações de depuração semelhantes a:

OAuth authentication failed: Access is restricted by your organization's policy. (HTTP 404)

Entre em contato com os administradores da sua organização para revisar e habilitar o acesso para seu aplicativo.

O botão Entrar está inativo ou exibe erro geral

Se o botão de entrada estiver inativo ou desabilitado, ou selecioná-lo exibir um erro geral de "A solicitação não pode ser processada", essa condição poderá indicar problemas temporários de autenticação ou sessão. Repita a consulta. Se o problema continuar, reinstale o aplicativo ou entre em contato com os administradores da sua organização.

O pop-up de entrada não abre

Habilite pop-ups para o site nas configurações do seu navegador e tente novamente.

O pop-up de entrada abre, mas fica preso ou nunca fecha

Se o pop-up de entrada abrir e o usuário concluir a autenticação, mas o pop-up nunca fechar e o Copilot não receber o resultado da autenticação, a referência do window.opener pop-up provavelmente foi destruída durante a cadeia de redirecionamento OAuth. Sem window.opener, o pop-up não pode comunicar o resultado da autenticação de volta ao Copilot. Um sintoma comum é que o login falha na primeira vez, mas é bem-sucedido na tentativa, pois as credenciais armazenadas em cache ignoram a página que destruiu window.opener.

Verifique os seguintes itens na cadeia de redirecionamento OAuth.

  • Anulação do window.openerJavaScript: Algumas páginas de logon definidas window.opener = null como uma medida de segurança geral contra tabnabbing reverso. Se qualquer página na cadeia de redirecionamento de autenticação executar esse código, o pop-up perderá sua conexão com o Copilot. Escopo tabnabbing proteções apenas para navegação iniciada pelo usuário e não limpar window.opener durante redirecionamentos in-popup.
  • Cross-Origin-Opener-Policy definido como same-origin: Se qualquer página na cadeia de redirecionamento exibir um Cross-Origin-Opener-Policy: same-origin cabeçalho de resposta, o navegador cortará permanentemente a window.opener referência na navegação entre origens. Verifique se todas as páginas em sua cadeia de redirecionamento OAuth omitem o Cross-Origin-Opener-Policy cabeçalho (cujo padrão é unsafe-none) ou defina-o explicitamente como unsafe-none.
  • Links usando rel="noopener": Ancore as tags com rel="noopener" a faixa window.opener da página de destino. Não use rel="noopener" para navegação no pop-up de autenticação.

Para depurar esse problema, abra as ferramentas de desenvolvedor do navegador na janela pop-up e digite window.opener no Console em cada etapa da cadeia de redirecionamento. Se window.opener retornar null antes do redirecionamento final, identifique qual página o limpou. Você também pode marcar os cabeçalhos de resposta da guia Rede para Cross-Origin-Opener-Policy valores em cada página da cadeia.

Erro de credenciais incorretas

Se você vir um erro de "Credenciais incorretas" no pop-up de entrada ou na resposta do chat, verifique se você está inserindo as credenciais corretas. Se o erro persistir, verifique se o usuário tem as permissões necessárias.

URL de entrada não encontrada

Desinstale e reinstale o aplicativo e tente entrar novamente.

Erro de servidor interno durante a autenticação

Verifique os detalhes no pop-up de autenticação e entre em contato com os administradores da sua organização se tiver problemas de permissão.

Se uma caixa de diálogo de consentimento for exibida solicitando permissões ou justificativa comercial, revise as permissões solicitadas e forneça uma justificativa comercial, se necessário. Se você não tiver certeza, ou se a caixa de diálogo de consentimento solicitar permissões que exijam consentimento do administrador, entre em contato com os administradores da sua organização.

Conteúdo relacionado

  • Last updated on