Resolver problemas de aplicações MCP no Microsoft 365 Copilot

Este guia fornece conselhos de resolução de problemas comuns que poderá encontrar ao desenvolver uma aplicação do Protocolo mcP (Model Context Protocol) para integrar com um agente declarativo dentro de Microsoft 365 Copilot.

Ativar o modo de programador

Ativar o modo de programador apresenta registos e erros nas respostas do agente. Estas informações são essenciais para a depuração. Para ativar o modo de programador, escreva o seguinte comando no Microsoft Copilot.

-developer on

As ferramentas MCP disponíveis para o agente são apresentadas na secção Ações das informações de depuração card. Para obter detalhes sobre as informações de depuração card, veja Utilizar o modo de programador no Microsoft 365 Copilot para testar e depurar agentes.

Problemas de deteção e entrada

Não existem ferramentas listadas

Se a secção Ações das informações de depuração card não listar nenhuma ferramenta MCP, marcar os seguintes itens.

  • Confirme que o servidor MCP está em execução e se está a ligar ao ponto final MCP correto no manifesto do plug-in.
  • Verifique se o manifesto do plug-in inclui as ferramentas esperadas na functions propriedade .
  • Verifique se o runtime do servidor MCP especificado na runtimes propriedade no manifesto do plug-in:
    • Referencia as ferramentas na mcp_tool_description propriedade ao:
      • Referenciar um ficheiro JSON que contém as descrições da ferramenta na file propriedade OU
      • Listar as descrições da ferramenta inline na tools propriedade
    • Inclui os nomes das ferramentas 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"
    ]
  }
]

As ferramentas não estão a ser acionadas a partir do chat do Copilot

  • Reveja as descrições da ferramenta e dos parâmetros para garantir que fornecem contexto suficiente. Considere reescrevê-los com "Utilizar esta função/parâmetro quando..." sintagma.
  • Mantenha descrições com menos de 1024 carateres. O texto para além de 1024 carateres é ignorado.
  • Certifique-se de que a visibilidade da ferramenta está definida corretamente.
    • Para aplicações MCP, _meta.ui.visibility inclui model.
    • Para aplicações openAI SDK, meta["openai/visibility"] está definido como public.

A ferramenta errada está selecionada

  • Evite ferramentas com nomes semelhantes ou descrições sobrepostas.
  • Adicione diferenciadores claros em descrições que explicam quando cada ferramenta deve ser utilizada.

Problemas com o Widget

O Widget não é composto

Se a ferramenta MCP correta for chamada, mas o widget da IU não for composto na resposta, é provável que o servidor MCP só devolva conteúdo estruturado sem componente de IU. Certifique-se de que o enlace de IU está configurado corretamente.

  • Para aplicações MCP, a definição de ferramentas inclui _meta.ui.resourceUri definido para um recurso HTML registado com o tipo text/html;profile=mcp-appMIME .
  • Para aplicações openAI SDK, a definição de ferramentas inclui _meta["openai/outputTemplate"] definido para um recurso HTML registado com o tipo text/html+skybridgeMIME .

Falha ao carregar o Widget

  • Abra as ferramentas de programador do seu browser e marcar para violações da Política de Segurança de Conteúdo (CSP) na consola do . Certifique-se de que os pedidos do URL do anfitrião do widget estão listados na lista de permissões. Para obter mais informações, veja Requisitos de servidor MCP para aplicações MCP.
  • Verifique se o widget compila todas as dependências HTML e JavaScript num único ficheiro sem recursos 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.
  • Confirme structuredContent ou _meta inclua os dados necessários.

O Widget tem uma barra de deslocamento dupla

O contentor anfitrião Copilot já tem um deslocamento com a altura máxima. Desative o deslocamento interno no widget ao definir overflow: hidden os estilos de contentor.

As etiquetas <a> de âncora não funcionam para ligações externas no Copilot. Em alternativa, utilize as APIs de plataforma adequadas.

  • Para aplicações MCP, utilize app.openLink.
  • Para aplicações openAI SDK, utilize window.openai.openExternal.

O ecrã inteiro não funciona em alguns anfitriões Copilot

A vista de ecrã inteiro não é suportada em todos os anfitriões Copilot. Como melhor prática, marcar sempre para capacidades de anfitrião e apresentar condicionalmente elementos de IU (como um botão de ecrã inteiro). Para obter mais informações, veja Verificar a disponibilidade da API.

Problemas de resposta

Problemas de expiração do resultado da ferramenta

Certifique-se de que as respostas da ferramenta enviadas através content ou structuredContent não são excessivamente grandes. Se o widget necessitar de metadados avançados que não sejam úteis para o modelo, como URLs de avatar ou detalhes específicos da IU, inclua os dados completos no _meta e forneça um resumo conciso no content. Esta abordagem garante que o modelo retém informações importantes ao mesmo tempo que suporta uma experiência multiturm eficaz.

Duplicar dados no widget e no resumo de texto

Resolva este problema com uma das seguintes opções:

  • Otimizar a separação de dados: utilize _meta para dados específicos do widget e content para resumos visíveis para modelos.
  • Formatação de orientação: utilize instruções no manifesto do agente declarativo para orientar a forma como as respostas são estruturadas e apresentadas.

Problemas de autenticação

Erro de correspondência do ID da aplicação entre a configuração de autenticação e o plug-in

Se vir erros nas suas informações de depuração card semelhante a:

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

Aceda ao portal do programador do Teams. Localize o registo do cliente OAuth ou do início de sessão único (SSO) e verifique se o ID da Aplicação no plug-in corresponde ao ID da Aplicação registado.

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

Se vir erros nas suas informações de depuração card semelhante a:

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

Aceda ao portal do programador do Teams. Localize o cliente OAuth ou o registo de cliente SSO e verifique se o URL do servidor MCP no plug-in corresponde ao URL base registado.

O ID de referência no manifesto do plug-in está incorreto ou em falta

Se vir erros nas suas informações de depuração card semelhante a:

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

Aceda ao portal do programador do Teams. Localize o registo do cliente OAuth ou do cliente SSO e verifique se o ID no runtime auth.reference_id do servidor MCP corresponde ao ID do registo no portal do programador.

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

Se vir erros nas suas informações de depuração card semelhante a:

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

Contacte os administradores da sua organização para rever e ativar o acesso à sua aplicação.

O botão iniciar sessão está inativo ou apresenta um erro geral

Se o botão de início de sessão estiver inativo ou desativado, ou se a seleção apresentar um erro geral "Não é possível processar o pedido", esta condição poderá indicar problemas temporários de autenticação ou sessão. Repita a consulta. Se o problema persistir, reinstale a aplicação ou contacte os administradores da sua organização.

Falha ao abrir o pop-up de início de sessão

Ative pop-ups para o site nas definições do browser e tente novamente.

Erro de credenciais incorretas

Se vir um erro "Credenciais incorretas" na resposta de pop-up ou chat de início de sessão, certifique-se de que está a introduzir as credenciais corretas. Se o erro persistir, certifique-se de que o utilizador tem as permissões necessárias.

URL de início de sessão não encontrado

Desinstale e reinstale a aplicação e, em seguida, tente iniciar sessão novamente.

Erro interno do servidor durante a autenticação

Verifique os detalhes no pop-up de autenticação e contacte os administradores da sua organização para obter problemas de permissões.

Se for apresentada uma caixa de diálogo de consentimento a pedir permissões ou justificação comercial, reveja as permissões pedidas e forneça uma justificação comercial, se necessário. Se não tiver a certeza ou se a caixa de diálogo de consentimento pedir permissões que exijam o consentimento do administrador, contacte os administradores da sua organização.

Conteúdo relacionado

  • Last updated on