Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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.
Pré-requisitos para aplicativos MCP
- Requisitos especificados em Requisitos para opções de extensibilidade do Copilot
- Um servidor MCP remoto que fornece widgets de interface do usuário ou que você pode modificar para implementar widgets da interface do usuário
- Uma ferramenta para exibir respostas do servidor MCP, como o Inspetor MCP
- 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 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/oAuthRedirectpara 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/oAuthConsentRedirectpara o Copilot - Visual Studio Code atualmente não suporta SSO para ferramentas de busca
-
- 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:
- 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
- Abra o navegador e vá para https://m365.cloud.microsoft/chat.
- Selecione o seu agente na barra lateral esquerda. Se não vir o 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 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.
Conteúdo relacionado
- Servidores MCP como recursos de plug-in
- Criar ou reutilizar servidores MCP
- Integrar e testar os componentes do plug-in
- Empacotar um plug-in
- Validar um plug-in
- Diretrizes de experiência do usuário para aplicativos MCP em agentes declarativos para Microsoft 365 Copilot
- Solucionar problemas de aplicativos MCP no Microsoft 365 Copilot
- Exemplos de interface do usuário interativa baseados em MCP para Microsoft 365 Copilot
- Criar plug-ins de um servidor MCP para o Microsoft 365 Copilot
- Visão geral dos aplicativos MCP
- SDK de aplicativos OpenAI