Adición de aplicaciones MCP a agentes declarativos en Microsoft 365 Copilot

Las aplicaciones MCP son widgets de interfaz de usuario interactivos que se ejecutan dentro de Microsoft 365 Copilot, con tecnología de servidores de Protocolo de contexto de modelo (MCP). Permiten a los agentes declarativos ir más allá de las respuestas de texto y ofrecer experiencias enriquecidas y procesables directamente en el chat de Copilot. Puede agregar aplicaciones MCP a los agentes declarativos agregando una acción basada en servidor MCP al agente y ampliando las herramientas de MCP usadas por el agente para incluir la interfaz de usuario. Microsoft 365 Copilot admite widgets de interfaz de usuario creados con los métodos siguientes.

• Aplicaciones MCP : una extensión a MCP que permite a los servidores MCP entregar interfaces de usuario interactivas a los hosts.
• SDK de OpenAI Apps : herramientas para crear aplicaciones chatGPT basadas en el estándar mcp apps con funcionalidad adicional de ChatGPT.

Por ejemplo, complementos de servidor MCP, consulte ejemplos de interfaz de usuario interactiva basada en MCP para Microsoft 365 Copilot en GitHub.

Para obtener más información sobre qué funcionalidades de MCP Apps o OpenAI Apps SDK se admiten, consulte Funcionalidades de aplicaciones MCP admitidas en Copilot.

Requisitos previos para aplicaciones MCP

• Requisitos especificados en Requisitos para las opciones de extensibilidad de Copilot
• Un servidor MCP remoto que proporciona widgets de interfaz de usuario o que puede modificar para implementar widgets de interfaz de usuario
• Una herramienta para ver las respuestas del servidor MCP, como mcp inspector
• Visual Studio Code
• Microsoft 365 Agents Toolkit (versión 6.6.1 o posterior)

Requisitos del servidor MCP para aplicaciones MCP

• Autenticación: se admiten OAuth 2.1 y Microsoft Entra inicio de sesión único (SSO). La autenticación anónima se admite con fines de desarrollo. Para obtener más información sobre la autenticación, consulte Configuración de la autenticación para complementos de API en agentes.
• Direcciones URL permitidas : el servidor MCP y el proveedor de identidades deben permitir las siguientes direcciones URL.
  • Dirección URL del host de widget para CORS: Copilot representa la interfaz de usuario del widget en un host específico del servidor MCP con la siguiente dirección URL: {hashed-mcp-domain}.widget-renderer.usercontent.microsoft.com, donde {hashed-mcp-domain} es el hash SHA-256 del dominio del servidor MCP. Puede usar el generador de direcciones URL del host de widget para generar la dirección URL del host en función de la dirección URL del servidor MCP.
  • URI de redireccionamiento de OAuth 2.1:
    • https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect para Copilot
    • https://vscode.dev/redirectpara Visual Studio Code para capturar herramientas mediante el kit de herramientas de agentes
  • Microsoft Entra URI de redireccionamiento de SSO:
    • https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect para Copilot
    • Visual Studio Code no admite actualmente el inicio de sesión único para capturar herramientas
• Widgets de interfaz de usuario : los widgets de la interfaz de usuario se deben implementar de acuerdo con los requisitos del SDK de aplicaciones de MCP o OpenAI Apps.

Procedimientos recomendados para aplicaciones MCP en Copilot

Diseño de la experiencia del usuario

Para obtener más información sobre los procedimientos recomendados de diseño de experiencia de usuario, consulte Instrucciones de experiencia del usuario para aplicaciones MCP en agentes declarativos para Microsoft 365 Copilot.

Comprobación de la disponibilidad de la API

No todas las window.openai.* API están disponibles en todas las plataformas o hosts. Las API que no son compatibles son undefined. Compruebe siempre la disponibilidad de la API y proporcione una reserva si la API no está disponible.

Ejemplos

Este patrón simple evita errores en tiempo de ejecución comprobando antes de llamar a la 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.
}

En este ejemplo, solo se representa un botón para entrar en modo de pantalla completa si el host admite la 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, el widget puede comprobar la disponibilidad de todas las API que usa en el inicio y habilitar o deshabilitar las características en consecuencia.

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
}

Creación de un agente declarativo

1. Abra Visual Studio Code y seleccione el icono Microsoft 365 Agents Toolkit (Kit de herramientas de agentes de Microsoft 365) en la barra de actividad de la izquierda.

2. Seleccione Crear un nuevo agente o aplicación en el panel de tareas Kit de herramientas de agentes.

   

3. Seleccione Agente declarativo.

4. Seleccione Agregar una acción y, a continuación, seleccione Iniciar con un servidor MCP. Si se le solicita, elija Servidor MCP remoto.

5. Escriba la dirección URL al servidor MCP.

6. Elija una ubicación para el proyecto del agente.

7. Escriba un nombre para el agente.

Cuando complete estos pasos, Agents Toolkit genera los archivos necesarios para el agente y abre una nueva ventana Visual Studio Code con el proyecto del agente cargado.

Actualización y transferencia local del agente

1. Abra el archivo .vscode/mcp.json . Seleccione el botón Iniciar en el editor de archivos.

2. Seleccione el botón ATK: Capturar acción de MCP en el editor de archivos y, a continuación, seleccione ai-plugin.json.

   

3. Seleccione las herramientas para que el agente use y seleccione Aceptar. Asegúrese de seleccionar al menos una herramienta que tenga un widget de interfaz de usuario.

4. Seleccione el tipo de autenticación aplicable.

   

   Importante

   Si el servidor MCP está en desarrollo y no implementa la autenticación, se omite este paso. Debe agregar manualmente la autenticación al manifiesto una vez que agregue la autenticación al servidor.

5. Seleccione el icono microsoft 365 Agents Toolkit en la barra de actividad de la izquierda.

6. En el panel Cuentas , seleccione Iniciar sesión en Microsoft 365. (Si ya ha iniciado sesión, continúe con el paso siguiente).

7. Confirme que tanto la carga de aplicaciones personalizadas habilitada comoel acceso de Copilot habilitado se muestran en su cuenta de Microsoft 365. Si no lo hacen, consulte con el administrador de la organización. Consulte Requisitos para las opciones de extensibilidad de Copilot para obtener más información.

8. En el panel Ciclo de vida , seleccione Aprovisionar.

9. Si se le solicita, agregue los detalles de autenticación.

10. Espere a que el kit de herramientas informe de que finaliza el aprovisionamiento.

Prueba del agente

1. Abra el explorador y vaya a https://m365.cloud.microsoft/chat.
2. Seleccione el agente en la barra lateral izquierda. Si no ve el agente, seleccione Todos los agentes.
3. Pida al agente que haga algo que invoque el servidor MCP.
4. Permitir que el agente se conecte al servidor MCP cuando se le solicite.
5. El agente representa el widget de interfaz de usuario.

Si el widget no aparece ni se comporta según lo esperado, consulte Solución de problemas de aplicaciones MCP en Microsoft 365 Copilot.

Funcionalidades de aplicaciones MCP admitidas en Copilot

Microsoft 365 Copilot admite las siguientes funcionalidades.

Puente de componentes

OpenAI Apps SDK	Aplicaciones MCP equivalentes	¿Se admite?
window.openai.toolInput	app.ontoolinput	✅
window.openai.toolOutput	app.ontoolresult	✅
window.openai.toolResponseMetadata	app.ontoolresult → params._meta	✅
window.openai.widgetState	—	✅
window.openai.setWidgetState(state)	No disponible directamente. Uso de mecanismos alternativos, incluidos 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 })	✅ (solo pantalla completa)
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 del descriptor de herramientas

OpenAI Apps SDK	Aplicaciones MCP equivalentes	¿Se admite?
_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"]	—	❌

Anotaciones de descriptor de herramientas

OpenAI Apps SDK	Aplicaciones MCP equivalentes	¿Se admite?
readOnlyHint	readOnlyHint	✅
destructiveHint	destructiveHint	❌
openWorldHint	openWorldHint	❌
idempotentHint	idempotentHint	❌

Campos de _meta de recursos de componente

OpenAI Apps SDK	Aplicaciones MCP equivalentes	¿Se admite?
_meta["openai/widgetDescription"]	—	❌
_meta["openai/widgetPrefersBorder"]	_meta.ui.prefersBorder	❌
_meta["openai/widgetCSP"]	_meta.ui.csp	✅
_meta["openai/widgetDomain"]	_meta.ui.domain	❌
—	_meta.ui.permissions	❌

Propiedades del objeto CSP

OpenAI Apps SDK	Aplicaciones MCP equivalentes	¿Se admite?
connect_domains	connectDomains	✅
resource_domains	resourceDomains	✅
frame_domains	frameDomains	❌
redirect_domains	—	❌
—	baseUriDomains	❌

Resultados de la herramienta proporcionados por el host _meta campos

OpenAI Apps SDK	Aplicaciones MCP equivalentes	¿Se admite?
_meta["openai/widgetSessionId"]	—	❌

Campos de _meta proporcionados por el cliente

OpenAI Apps SDK	Aplicaciones MCP equivalentes	¿Se admite?
_meta["openai/locale"]	_meta["openai/locale"]	✅
_meta["openai/userAgent"]	_meta["openai/userAgent"]	✅
_meta["openai/userLocation"]	_meta["openai/userLocation"]	✅
_meta["openai/subject"]	—	❌

Preguntas más frecuentes sobre las aplicaciones MCP en Copilot

¿Qué son las aplicaciones MCP?

Las aplicaciones MCP son widgets de interfaz de usuario interactivos entregados por servidores MCP que se representan directamente dentro de Microsoft 365 Copilot. Amplían los agentes declarativos más allá de las respuestas de solo texto, lo que permite experiencias enriquecidas, como visualizaciones de datos, formularios e interfaces de administración de tareas.

¿Cuál es la diferencia entre MCP Apps y OpenAI Apps SDK?

MCP Apps es una extensión abierta al estándar MCP que permite a los servidores MCP entregar interfaces de usuario interactivas a cualquier host compatible. El SDK de OpenAI Apps se basa en el estándar MCP Apps y agrega funcionalidad adicional específica de ChatGPT. Microsoft 365 Copilot admite ambos, aunque no todas las funcionalidades están disponibles. Consulte Funcionalidades de aplicaciones MCP admitidas en Copilot para obtener más información.

¿Puedo usar aplicaciones MCP sin autenticación durante el desarrollo?

Sí. La autenticación anónima se admite con fines de desarrollo. Sin embargo, debe agregar autenticación antes de realizar la implementación en producción. OAuth 2.1 y Microsoft Entra inicio de sesión único (SSO) son los métodos de autenticación admitidos. Para obtener más información, consulte Configuración de la autenticación para complementos de API en agentes.

Contenido relacionado

• Compilación de complementos desde un servidor MCP para Microsoft 365 Copilot
• Instrucciones de experiencia del usuario para aplicaciones MCP en agentes declarativos para Microsoft 365 Copilot
• Solución de problemas de aplicaciones MCP en Microsoft 365 Copilot
• Introducción a las aplicaciones MCP
• OpenAI Apps SDK
• Ejemplos de interfaz de usuario interactiva basada en MCP para Microsoft 365 Copilot