Adicionar aplicativos MCP a agentes declarativos no Microsoft 365 Copilot

Dica

Recomendado: Comece com o Work IQ Dev Tools para cenários de agente declarativo e plug-in pro-código suportados. Consulte o guia de início rápido do WIQD. As instruções baseadas em toolkits permanecem disponíveis para projetos e fluxos de trabalho existentes que o exigem. Verifique o suporte à capacidade e à experiência de destino antes de escolher uma ferramenta: o WIQD não tem como alvo agentes de mecanismo personalizados.

As aplicações MCP são widgets IU interativos que são executados no Microsoft 365 Copilot, com tecnologia de servidores MCP (Model Context Protocol). Permitem que os agentes declarativos vão além das respostas de texto e forneçam experiências ricas e acionáveis diretamente no chat do Copilot. Você pode adicionar aplicativos MCP aos seus agentes declarativos adicionando um plug-in baseado em servidor MCP cujas ferramentas retornam a interface do usuário interativa. Microsoft 365 Copilot suporta widgets de IU criados com os seguintes métodos.

  • MCP Apps - uma extensão para MCP que permite que os servidores MCP forneçam interfaces de usuário interativas para hosts.
  • OpenAI Apps SDK - ferramentas para criar aplicativos ChatGPT baseados no padrão MCP Apps com funcionalidade extra ChatGPT.

Por exemplo, plug-ins de servidor MCP, consulte Exemplos de interface do usuário interativa baseada em MCP para Microsoft 365 Copilot no GitHub.

Para obter detalhes sobre que funcionalidades MCP Apps ou OpenAI Apps SDK são suportadas, consulte Suportadas capacidades MCP Apps no Copilot.

Uma captura de ecrã de uma aplicação MCP a compor um widget Tarefas de sprints inline no Microsoft 365 Copilot

Uma captura de ecrã de uma aplicação MCP a compor um widget de tarefas Sprint no modo de ecrã inteiro no Microsoft 365 Copilot

Pré-requisitos para aplicativos MCP

Requisitos do servidor MCP para aplicativos MCP

  • Autenticação - o Copilot suporta OAuth 2.1 e Microsoft Entra início de sessão único (SSO). Para fins de desenvolvimento, o Copilot suporta a autenticação anónima ao utilizar a opção Nenhum no Agents Toolkit. Para obter mais informações sobre autenticação, consulte Configurar autenticação para plug-ins de API em agentes.
  • URLs permitidos - O servidor MCP e o provedor de identidade devem permitir as seguintes URLs.
    • URL do anfitrião do widget para o CORS - o Copilot processa a IU do widget sob um anfitrião específico do servidor MCP com o seguinte URL: {hashed-mcp-domain}.widget-renderer.usercontent.microsoft.com, em que {hashed-mcp-domain} é o hash SHA-256 do domínio do seu servidor MCP. Você pode usar o Gerador de URL do Host do Widget para gerar a URL do host com base na URL do seu servidor MCP.
    • URIs de redirecionamento OAuth 2.1:
      • https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect para o Copilot
      • https://vscode.dev/redirectpara Visual Studio Code buscar ferramentas usando o Agents Toolkit
    • Microsoft Entra URIs de redirecionamento SSO:
      • https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect para o Copilot
      • Visual Studio Code atualmente não suporta SSO para ferramentas de busca
  • Widgets de interface do usuário - Implemente widgets de interface do usuário de acordo com os requisitos do SDK do MCP Apps ou OpenAI Apps.

Melhores práticas para aplicações MCP no Copilot

Design da experiência do utilizador

Para obter mais informações sobre práticas recomendadas de design de UX, consulte Diretrizes de experiência do usuário para aplicativos MCP em agentes declarativos para Microsoft 365 Copilot.

Verificar a disponibilidade da API

Nem todas as window.openai.* APIs estão disponíveis em todas as plataformas ou hosts. APIs não suportadas são undefined. Sempre marcar a disponibilidade da API e forneça um fallback se a API não estiver disponível.

Exemplos

Esse padrão simples evita erros de tempo de execução verificando antes de chamar a API.

if (window.openai.callTool) {
  const result = await window.openai.callTool({ name: 'myTool', params: {} });
} else {
  // Handle unsupported case — show fallback UI, skip the feature, etc.
}

Neste exemplo, um botão para entrar no modo de tela cheia é renderizado somente se o host suportar a requestDisplayMode API.

function FullScreenButton() {
  // Don't render the button if the host doesn't support it
  if (!window.openai.requestDisplayMode) {
    return null;
  }

  return (
    <button onClick={() => window.openai.requestDisplayMode({ mode: 'fullscreen' })}>
      Enter Fullscreen
    </button>
  );
}

Em alternativa, o widget pode marcar disponibilidade de todas as APIs que utiliza no arranque e ativar ou desativar funcionalidades em conformidade.

interface PlatformCapabilities {
  canCallTools: boolean;
  canChangeDisplayMode: boolean;
  canSendMessages: boolean;
}

function detectCapabilities(): PlatformCapabilities {
  return {
    canCallTools: !!window.openai.callTool,
    canChangeDisplayMode: !!window.openai.requestDisplayMode,
    canSendMessages: !!window.openai.sendMessage,
  };
}

// Use at widget startup
const capabilities = detectCapabilities();

if (!capabilities.canCallTools) {
  // Show a reduced-functionality experience
}

Criar e fazer sideload do agente

Criar um agente declarativo a partir de um servidor MCP, configurar a autenticação e fazer o sideload são os mesmos, quer o servidor devolva ou não widgets da interface do usuário. Para obter o passo a passo completo, consulte Criar um plug-in para um agente declarativo de um servidor MCP.

Tenha em mente as seguintes considerações sobre aplicativos MCP ao seguir esse passo a passo:

  • Seu servidor MCP deve retornar widgets de interface do usuário de acordo com os requisitos do MCP Apps ou OpenAI Apps SDK. Consulte Requisitos do servidor MCP para aplicativos MCP.
  • Por padrão, o agente usa a descoberta dinâmica de ferramentas e resolve as ferramentas do servidor - incluindo ferramentas que retornam widgets da interface do usuário - em tempo de execução, para que você não precise adicionar ferramentas manualmente. Se, em vez disso, afixar um conjunto fixo de ferramentas, certifique-se de que inclui, pelo menos, uma ferramenta que devolve um widget da IU.
  • Se o servidor MCP ainda estiver em desenvolvimento e não implementar autenticação, selecione Nenhum como o tipo de autenticação. Adicione autenticação antes de implantar na produção.

Testar o agente

  1. Abra o navegador e vá para https://m365.cloud.microsoft/chat.
  2. Selecione o seu agente na barra lateral esquerda. Se não vir o seu agente, selecione Todos os agentes.
  3. Peça ao agente para fazer algo que invoque seu servidor MCP.
  4. Permita que o agente se conecte ao servidor MCP quando solicitado.
  5. Confirme se o agente compõe o widget da interface do usuário.

Se o widget não aparecer ou se comportar conforme esperado, consulte Solução de problemas de aplicativos MCP no Microsoft 365 Copilot.

Capacidades de Aplicações MCP suportadas no Copilot

Microsoft 365 Copilot suporta as seguintes capacidades.

Ponte de componentes

OpenAI Apps SDK Equivalente a MCP Apps Com suporte?
window.openai.toolInput app.ontoolinput ✅
window.openai.toolOutput app.ontoolresult ✅
window.openai.toolResponseMetadata app.ontoolresult → params._meta ✅
window.openai.widgetState — ✅
window.openai.setWidgetState(state) Não está diretamente disponível. Utilizar mecanismos alternativos, incluindo app.updateModelContext() ✅
window.openai.callTool(name, args) app.callServerTool({ name, arguments }) ✅
window.openai.sendFollowUpMessage({ prompt }) app.sendMessage({ ... }) ✅
window.openai.uploadFile(file) — ❌
window.openai.getFileDownloadUrl({ fileId }) — ❌
window.openai.requestDisplayMode(...) app.requestDisplayMode({ mode }) ✅ (apenas em ecrã inteiro)
window.openai.requestModal(...) — ❌
window.openai.notifyIntrinsicHeight(...) app.sendSizeChanged({ width, height }) ✅
window.openai.openExternal({ href }) app.openLink({ url }) ✅
window.openai.setOpenInAppUrl({ href }) — ✅
window.openai.theme app.getHostContext()?.theme ✅
window.openai.displayMode app.getHostContext()?.displayMode ✅
window.openai.maxHeight app.getHostContext()?.viewport?.maxHeight ✅
window.openai.safeArea app.getHostContext()?.safeAreaInsets ✅
window.openai.view — ✅
window.openai.userAgent app.getHostContext()?.userAgent ✅
window.openai.locale app.getHostContext()?.locale ✅
— app.ontoolinputpartial ❌
— app.ontoolcancelled ❌
— app.getHostContext()?.availableDisplayModes ❌
— app.getHostContext()?.toolInfo ❌
— app.onhostcontextchanged ❌
— app.onteardown ❌
— app.sendLog({ level, data }) ❌
— app.getHostVersion() ❌
— app.getHostCapabilities() ✅

Campos _meta descritor de ferramentas

OpenAI Apps SDK Equivalente a MCP Apps Com suporte?
_meta["openai/outputTemplate"] _meta.ui.resourceUri ✅
_meta["openai/widgetAccessible"] _meta.ui.visibility (cadeia[]) ❌
_meta["openai/visibility"] _meta.ui.visibility (cadeia[]) ✅
_meta["openai/toolInvocation/invoking"] — ❌
_meta["openai/toolInvocation/invoked"] — ❌
_meta["openai/fileParams"] — ❌
_meta["securitySchemes"] — ❌

Anotações do descritor da ferramenta

OpenAI Apps SDK Equivalente a MCP Apps Com suporte?
readOnlyHint readOnlyHint ✅
destructiveHint destructiveHint ❌
openWorldHint openWorldHint ❌
idempotentHint idempotentHint ❌

Campos de _meta de recursos do componente

OpenAI Apps SDK Equivalente a MCP Apps Com suporte?
_meta["openai/widgetDescription"] — ❌
_meta["openai/widgetPrefersBorder"] _meta.ui.prefersBorder ❌
_meta["openai/widgetCSP"] _meta.ui.csp ✅
_meta["openai/widgetDomain"] _meta.ui.domain ❌
— _meta.ui.permissions ❌

Propriedades no objeto CSP

OpenAI Apps SDK Equivalente a MCP Apps Com suporte?
connect_domains connectDomains ✅
resource_domains resourceDomains ✅
frame_domains frameDomains ❌
redirect_domains — ❌
— baseUriDomains ❌

Campos de _meta de resultado da ferramenta fornecida pelo anfitrião

OpenAI Apps SDK Equivalente a MCP Apps Com suporte?
_meta["openai/widgetSessionId"] — ❌

Campos _meta fornecidos pelo cliente

SDK de aplicativos OpenAI Equivalente do MCP Apps Com suporte?
_meta["openai/locale"] _meta["openai/locale"] ✅
_meta["openai/userAgent"] _meta["openai/userAgent"] ✅
_meta["openai/userLocation"] _meta["openai/userLocation"] ✅
_meta["openai/subject"] — ❌

Perguntas frequentes sobre aplicativos MCP no Copilot

O que são aplicativos MCP?

Os aplicativos MCP são widgets de interface do usuário interativos fornecidos por servidores MCP que são renderizados diretamente no Microsoft 365 Copilot. Eles estendem os agentes declarativos para além das respostas somente de texto, permitindo experiências avançadas, como visualizações de dados, formulários e interfaces de gerenciamento de tarefas.

Qual é a diferença entre o MCP Apps e o SDK do OpenAI Apps?

MCP Apps é uma extensão aberta para o padrão MCP que permite que os servidores MCP forneçam interfaces de usuário interativas para qualquer host compatível. O SDK do OpenAI Apps se baseia no padrão MCP Apps e adiciona funcionalidades extras específicas ao ChatGPT. O Microsoft 365 Copilot dá suporte a ambos, embora nem todos os recursos estejam disponíveis. Confira Recursos de aplicativos MCP com suporte no Copilot para obter detalhes.

Posso usar aplicativos MCP sem autenticação durante o desenvolvimento?

Sim. A autenticação anônima tem suporte para fins de desenvolvimento. No entanto, você precisa adicionar autenticação antes da implantação na produção. O OAuth 2.1 e o SSO (logon único) do Microsoft Entra são os métodos de autenticação com suporte. Para obter detalhes, consulte Configurar a autenticação para plug-ins de API em agentes.