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 uma ação baseada no servidor MCP ao seu agente e estendendo as ferramentas MCP usadas pelo agente para incluir a interface do usuário. 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.6.1 ou posterior)

Requisitos do servidor MCP para aplicativos MCP

Autenticação - OAuth 2.1 e SSO (logon único) do Microsoft Entra são suportados. A autenticação anônima tem suporte para fins de desenvolvimento. Para obter detalhes sobre autenticação, consulte Configurar a autenticação para plug-ins de API em agentes.
URLs permitidas - as URLs a seguir devem ser permitidas pelo servidor MCP e pelo provedor de identidade.
- 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 Kit de Ferramentas de Agentes
- 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 : os widgets de interface do usuário devem ser implementados de acordo com os requisitos do SDK dos Aplicativos MCP ou do OpenAI Apps.

Práticas recomendadas para aplicativos MCP no Copilot

Design de experiência do usuário

Para obter detalhes 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/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 um agente declarativo

Abra o Visual Studio Code e selecione o ícone do Kit de Ferramentas para Agentes do Microsoft 365 na Barra de Atividades à esquerda.
Selecione Criar um novo agente/aplicativo no painel de tarefas Kit de ferramentas para agentes.
Selecione o Agente Declarativo.
Selecione Adicionar uma Ação e, em seguida, selecione Iniciar com um Servidor MCP. Se solicitado, escolha Servidor MCP remoto.
Insira a URL para seu servidor MCP.
Escolha um local para o projeto de agente.
Insira um nome para o agente.

Quando você conclui essas etapas, o Agents Toolkit gera os arquivos necessários para o agente e abre uma nova janela do Visual Studio Code com o projeto do agente carregado.

Atualize e faça o sideload do agente

Abra o arquivo .vscode/mcp.json . Selecione o botão Iniciar no editor de arquivos.
Selecione o botão ATK: Fetch action from MCP no editor de arquivos e selecione ai-plugin.json.
Selecione as ferramentas para o agente usar e selecione OK. Certifique-se de selecionar pelo menos uma ferramenta que tenha um widget de interface do usuário.
Selecione o tipo de autenticação aplicável.

Importante

Se o servidor MCP estiver em desenvolvimento e não implementar a autenticação, esta etapa será ignorada. Você precisa adicionar manualmente a autenticação ao seu manifesto depois de adicionar a autenticação ao servidor.
Selecione o ícone do Microsoft 365 Agents Toolkit na Barra de Atividades à esquerda.
No painel Contas , selecione Entrar no Microsoft 365. (Se você já estiver conectado, vá para a próxima etapa).
Confirme se o Upload de aplicativo personalizado habilitado e o Acesso ao Copilot habilitado são exibidos em sua conta do Microsoft 365. Caso contrário, marque com o administrador da sua organização. Consulte Requisitos para opções de extensibilidade do Copilot para obter detalhes.
No painel Ciclo de Vida , selecione Provisionar.
Se solicitado, adicione seus detalhes de autenticação.
Aguarde até que o kit de ferramentas informe que concluiu o provisionamento.

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.
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?

Last updated on 2026-08-24