Solución de problemas de las aplicaciones de MCP en Microsoft 365 Copilot

En esta guía se proporcionan consejos de solución de problemas para problemas comunes que pueden surgir al desarrollar una aplicación de Protocolo de contexto de modelo (MCP) para integrarla con un agente declarativo dentro de Microsoft 365 Copilot.

Habilitar el modo de desarrollador

Al habilitar el modo de desarrollador , se exponen registros y errores en las respuestas del agente. Esta información es esencial para la depuración. Para habilitar el modo de desarrollador, escriba el siguiente comando en Microsoft Copilot.

-developer on

Las herramientas de MCP disponibles para el agente se muestran en la sección Acciones de la tarjeta de información de depuración. Para obtener más información sobre la tarjeta de información de depuración, consulte Usar el modo de desarrollador en Microsoft 365 Copilot para probar y depurar agentes.

Problemas de detección y entrada

No se enumeran herramientas

Si la sección Acciones de la tarjeta de información de depuración no muestra ninguna herramienta de MCP, compruebe lo siguiente:

  • Confirme que su servidor MCP se esté ejecutando y que se esté conectando al punto de conexión de MCP correcto en el manifiesto del complemento.
  • Confirme que la autenticación es correcta. Muchos servidores MCP no devuelven ninguna herramienta hasta que el usuario inicia sesión, por lo que un inicio de sesión erróneo u omitido puede dar lugar a una lista de herramientas vacía.

Detección de herramientas dinámicas

Si el agente usa la detección dinámica de herramientas (el valor predeterminado), las herramientas se resuelven desde el servidor en tiempo de ejecución. Comprueba que:

  • El RemoteMCPServer entorno de ejecución se establece run_for_functions en ["*"] y la matriz de nivel functions superior está vacía.
  • El método del tools/list servidor devuelve herramientas. Puede inspeccionar la respuesta utilizando una herramienta como MCP Inspector.
  • Una herramienta recién descubierta o modificada no se retiene en la validación en tiempo de ejecución. Compruebe la información de depuración para ver si hay errores de validación.
"runtimes": [
  {
    "type": "RemoteMCPServer",
    "spec": {
      "url": "https://api.contoso.com/mcp"
    },
    "run_for_functions": [
      "*"
    ]
  }
]

Herramientas ancladas

Si ancló un conjunto fijo de herramientas, compruebe que el tiempo de ejecución del servidor MCP especificado en la runtimes propiedad del manifiesto del complemento:

  • Incluye las herramientas esperadas en la propiedad de nivel functions superior.
  • Hace referencia a las herramientas de la mcp_tool_description propiedad mediante:
    • Hacer referencia a un archivo JSON que contiene las descripciones de la herramienta en la file propiedad O
    • Listado de las descripciones de herramientas en línea en la tools propiedad
  • Incluye los nombres de herramientas en la run_for_functions propiedad.
"runtimes": [
  {
    "type": "RemoteMCPServer",
    "spec": {
      "url": "https://api.contoso.com/mcp",
      "mcp_tool_description": {
        "file": "mcp-tools.json"
      }
    },
    "run_for_functions": [
      "get_widget",
      "create_widget"
    ]
  }
]

Las herramientas no se activan desde el chat de Copilot

  • Revisa las descripciones de las herramientas y los parámetros para asegurarte de que proporcionan suficiente contexto. Considere reescribirlos usando "Use esta función/parámetro cuando..." fraseo.
  • Mantén las descripciones con menos de 1024 caracteres. Se omiten los textos con más de 1024 caracteres.
  • Asegúrese de que la visibilidad de la herramienta esté configurada correctamente.
    • Para las aplicaciones de MCP, _meta.ui.visibility incluye model.
    • Para las aplicaciones del SDK de OpenAI, meta["openai/visibility"] se establece en public.

Se ha seleccionado la herramienta incorrecta

  • Evita las herramientas con nombres similares o descripciones superpuestas.
  • Agregue diferenciadores claros en las descripciones que expliquen cuándo se debe usar cada herramienta.

Problemas de widget

El widget no se representa

Si se llama a la herramienta MCP correcta, pero el widget de interfaz de usuario no se representa en la respuesta, es probable que el servidor MCP solo devuelva contenido estructurado sin componente de interfaz de usuario. Asegúrese de que el enlace de interfaz de usuario está configurado correctamente.

  • Para las aplicaciones de MCP, la definición de herramienta incluye _meta.ui.resourceUri la definición de un recurso HTML registrado con tipo text/html;profile=mcp-appMIME.
  • Para las aplicaciones del SDK de OpenAI, la definición de la herramienta incluye _meta["openai/outputTemplate"] la definición de un recurso HTML registrado con el tipo text/html+skybridgeMIME.

El widget no se carga

  • Abra las herramientas para desarrolladores de su explorador y compruebe si hay infracciones de la directiva de seguridad de contenido (CSP) en la consola. Asegúrese de que las solicitudes de la dirección URL de host del widget estén en la lista de permitidos. Para obtener más información, consulte Requisitos del servidor de MCP para las aplicaciones de MCP.
  • Compruebe que el widget compila todas las dependencias de HTML y JavaScript en un único archivo sin recursos externos sin resolver.

El widget se carga sin datos

  • Compruebe la estructura de respuesta de la herramienta.
    • content debe contener solo los datos (modelo).
    • structuredContent Debe contener tanto los datos como el widget.
    • _meta debe contener solo el widget.
  • Asegúrate de que structuredContent los datos necesarios o _meta los incluya.

El widget tiene una doble barra de desplazamiento

El contenedor del host de Copilot ya tiene un desplazamiento con altura máxima. Deshabilita el desplazamiento interno en tu widget configurando overflow: hidden tus estilos de contenedor.

Las etiquetas de delimitador <a> no funcionan para vínculos externos en Copilot. En su lugar, usa las API de plataforma adecuadas.

  • Para las aplicaciones de MCP, use app.openLink.
  • Para las aplicaciones del SDK de OpenAI, use window.openai.openExternal.

La pantalla completa no funciona en algunos hosts de Copilot

La vista de pantalla completa no se admite en todos los hosts de Copilot. Como práctica recomendada, compruebe siempre las funcionalidades del host y muestre condicionalmente los elementos de la interfaz de usuario (como un botón de pantalla completa). Para obtener más información, consulte Verificación de la disponibilidad de la API.

Problemas de respuesta

Problemas de caducidad del resultado de la herramienta

Asegúrese de que las respuestas de la herramienta se content envíen o structuredContent no sean excesivamente grandes. Si el widget requiere metadatos enriquecidos que no son útiles para el modelo, como direcciones URL de avatar o detalles específicos de la interfaz de usuario, incluya los datos completos en _meta y proporcione un resumen conciso en content. Este enfoque garantiza que el modelo retenga información clave al tiempo que respalda una experiencia efectiva de múltiples turnos.

Datos duplicados en el widget y el resumen de texto

Resuelva este problema mediante una de las siguientes opciones:

  • Optimizar la separación de datos: úselo _meta para datos específicos de widgets y content resúmenes visibles para modelos.
  • Dirigir el formato: use las instrucciones del manifiesto de agente declarativo para guiar cómo se estructuran y presentan las respuestas.

Problemas de autenticación

Para los problemas de autenticación (como errores de inicio de sesión, errores de token, solicitudes de consentimiento y discrepancias en la configuración de autenticación), consulte Solución de problemas de autenticación de complementos MCP y API.