Adicionar aplicativos MCP a agentes declarativos no Microsoft 365 Copilot

Os aplicativos MCP são widgets de interface do usuário interativos executados no Microsoft 365 Copilot, com servidores MCP (Model Context Protocol). Elas permitem que agentes declarativos vão além das respostas de texto e ofereçam experiências avançadas 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 interface do usuário interativa. O Microsoft 365 Copilot dá suporte a widgets de interface do usuário criados usando os métodos a seguir.

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

Para obter exemplos de plug-ins de servidor MCP, consulte Exemplos de interface do usuário interativa baseados em MCP para o Microsoft 365 Copilot no GitHub.

Para obter detalhes sobre quais recursos do MCP Apps ou do OpenAI Apps SDK são compatíveis, consulte Recursos de MCP Apps com suporte no Copilot.

Pré-requisitos para aplicativos MCP

Requisitos especificados em Requisitos para opções de extensibilidade do Copilot
Um servidor MCP remoto que fornece widgets de UI ou que você pode modificar para implementar widgets de UI
Uma ferramenta para exibir respostas do servidor MCP, como o MCP Inspector
Visual Studio Code
Microsoft 365 Agents Toolkit (versão 6.12.0 ou posterior)

Requisitos do servidor MCP para aplicativos MCP

Autenticação – o Copilot dá suporte ao OAuth 2.1 e ao SSO (logon único) do Microsoft Entra. Para fins de desenvolvimento, o Copilot dá suporte à autenticação anônima usando a opção Nenhum no Kit de Ferramentas de Agentes. Para obter mais informações sobre autenticação, consulte Configurar a autenticação para plug-ins de API em agentes.
URLs permitidas – o servidor MCP e o provedor de identidade devem permitir as URLs a seguir.
- URL do host de widget para CORS – o Copilot renderiza a interface do usuário do widget em um host específico do servidor MCP com a seguinte URL: {hashed-mcp-domain}.widget-renderer.usercontent.microsoft.com, onde {hashed-mcp-domain} está o hash SHA-256 do domínio do servidor MCP. Você pode usar o Gerador de URL do host de widget para gerar a URL do host com base na URL do servidor MCP.
- URIs de redirecionamento do OAuth 2.1:
  - https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect para Copilot
  - https://vscode.dev/redirectpara que o Visual Studio Code busque ferramentas usando o Agents Toolkit
- URIs de redirecionamento do SSO do Microsoft Entra:
  - https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect para Copilot
  - No momento, o Visual Studio Code não dá suporte ao 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 do OpenAI Apps.

Práticas recomendadas para aplicativos MCP no Copilot

Design de experiência do usuário

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

Verificar a disponibilidade da API

Nem todas as window.openai.* APIs estão disponíveis em todas as plataformas ou hosts. As APIs sem suporte são undefined. Sempre marque 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 inteira será renderizado somente se o host der suporte à 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>
  );
}

Como alternativa, o widget pode marcar a disponibilidade de todas as APIs usadas na inicialização e habilitar ou desabilitar os recursos de acordo.

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 dele são os mesmos, independentemente de o servidor retornar ou não widgets de interface do usuário. Para obter o passo a passo completo, consulte Criar um plug-in para um agente declarativo de um servidor MCP.

Lembre-se das seguintes considerações sobre os 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 SDK do MCP Apps ou do OpenAI Apps. 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 de interface do usuário, em tempo de execução, para que você não precise adicionar ferramentas manualmente. Se, em vez disso, você fixar um conjunto fixo de ferramentas, inclua pelo menos uma ferramenta que retorne um widget de interface do usuário.
Se o servidor MCP ainda estiver em desenvolvimento e não implementar a autenticação, selecione Nenhum como o tipo de autenticação. Adicione autenticação antes de implantar na produção.

Testar o agente

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

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

Recursos de aplicativos MCP com suporte no Copilot

O Microsoft 365 Copilot dá suporte aos seguintes recursos.

Ponte de componente

SDK de aplicativos OpenAI	Equivalente do 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á disponível diretamente. Use 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 })`	✅ (somente tela inteira)
`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 de _meta descritor de ferramenta

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

Anotações do descritor da ferramenta

SDK de aplicativos OpenAI	Equivalente do MCP Apps	Com suporte?
`readOnlyHint`	`readOnlyHint`	✅
`destructiveHint`	`destructiveHint`	❌
`openWorldHint`	`openWorldHint`	❌
`idempotentHint`	`idempotentHint`	❌

Campos de _meta de recursos do componente

SDK de aplicativos OpenAI	Equivalente do 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

SDK de aplicativos OpenAI	Equivalente do MCP Apps	Com suporte?
`connect_domains`	`connectDomains`	✅
`resource_domains`	`resourceDomains`	✅
`frame_domains`	`frameDomains`	❌
`redirect_domains`	—	❌
—	`baseUriDomains`	❌

Campos _meta resultado da ferramenta fornecida pelo host

SDK de aplicativos OpenAI	Equivalente do MCP Apps	Com suporte?
`_meta["openai/widgetSessionId"]`	—	❌

Campos de _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.

Comentários

Esta página foi útil?

Última atualização em 2026-09-30