Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
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
RemoteMCPServerentorno de ejecución se establecerun_for_functionsen["*"]y la matriz de nivelfunctionssuperior está vacía. - El método del
tools/listservidor 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
functionssuperior. - Hace referencia a las herramientas de la
mcp_tool_descriptionpropiedad mediante:- Hacer referencia a un archivo JSON que contiene las descripciones de la herramienta en la
filepropiedad O - Listado de las descripciones de herramientas en línea en la
toolspropiedad
- Hacer referencia a un archivo JSON que contiene las descripciones de la herramienta en la
- Incluye los nombres de herramientas en la
run_for_functionspropiedad.
"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.visibilityincluyemodel. - Para las aplicaciones del SDK de OpenAI,
meta["openai/visibility"]se establece enpublic.
- Para las aplicaciones de MCP,
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.resourceUrila definición de un recurso HTML registrado con tipotext/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 tipotext/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.
-
contentdebe contener solo los datos (modelo). -
structuredContentDebe contener tanto los datos como el widget. -
_metadebe contener solo el widget.
-
- Asegúrate de que
structuredContentlos datos necesarios o_metalos 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.
Los hipervínculos en el widget no se abren
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
_metapara datos específicos de widgets ycontentresú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.