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

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

Habilitación del modo de desarrollador

Al habilitar el modo de desarrollador , se exponen los registros y los 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 aparecen 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 Uso del modo de desarrollador en Microsoft 365 Copilot para probar y depurar agentes.

Problemas de detección y entrada

No se muestra ninguna herramienta

Si la sección Acciones de la tarjeta de información de depuración no muestra ninguna herramienta MCP, compruebe los siguientes elementos.

  • Confirme que el servidor MCP se está ejecutando y que se está conectando al punto de conexión mcp correcto en el manifiesto del complemento.
  • Compruebe que el manifiesto del complemento incluye las herramientas esperadas en la functions propiedad .
  • Compruebe que el tiempo de ejecución del servidor MCP especificado en la runtimes propiedad del manifiesto del complemento:
    • 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 OR
      • Enumeración de las descripciones de la herramienta insertadas en la tools propiedad
    • Incluye los nombres de la herramienta en la run_for_functions propiedad .
"runtimes": [
  {
    "type": "RemoteMCPServer",
    "spec": {
      "url": "https://api.contoso.com/mcp",
      "mcp_tool_description": "mcp-tools.json"
    },
    "run_for_functions": [
      "get_widget",
      "create_widget"
    ]
  }
]

Herramientas que no se desencadenan desde el chat de Copilot

  • Vuelva a consultar las descripciones de herramientas y parámetros para asegurarse de que proporcionan un contexto suficiente. Considere la posibilidad de volver a escribirlas con "Use this function/parameter when..." (Usar esta función o parámetro cuando..." fraseo.
  • Mantenga las descripciones en menos de 1024 caracteres. Se omite el texto de más de 1024 caracteres.
  • Asegúrese de que la visibilidad de la herramienta está establecida correctamente.
    • En el caso de las aplicaciones MCP, _meta.ui.visibility incluye model.
    • Para las aplicaciones del SDK de OpenAI, meta["openai/visibility"] se establece en public.

La herramienta incorrecta está seleccionada

  • Evite herramientas con nombres similares o descripciones superpuestas.
  • Agregue diferenciadores claros en 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 ningún componente de interfaz de usuario. Asegúrese de que el enlace de la interfaz de usuario está configurado correctamente.

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

No se puede cargar el widget

  • Abra las herramientas de desarrollo del explorador y compruebe si hay infracciones de directiva de seguridad de contenido (CSP) en la consola. Asegúrese de que las solicitudes de la dirección URL del host del widget aparecen en la lista de permitidos. Para obtener más información, consulte Requisitos del servidor MCP para aplicaciones MCP.
  • Compruebe que el widget compila todas las dependencias 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 los datos y el widget.
    • _meta debe contener solo el widget.
  • Asegúrese structuredContent o _meta incluya los datos necesarios.

El widget tiene una barra de desplazamiento doble

El contenedor host de Copilot ya tiene un desplazamiento con altura máxima. Deshabilite el desplazamiento interno en el widget estableciendo overflow: hidden en los estilos de contenedor.

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

  • Para las aplicaciones 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 a pantalla completa no se admite en todos los hosts de Copilot. Como procedimiento recomendado, 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 Comprobación de la disponibilidad de la API.

Problemas de respuesta

Problemas de expiración del resultado de la herramienta

Asegúrese de que las respuestas de la herramienta enviadas a través content de 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 conserva la información clave al tiempo que admite una experiencia de multiturno eficaz.

Datos duplicados en el widget y el resumen de texto

Para resolver este problema, use una de las siguientes opciones:

  • Optimizar la separación de datos: se usa _meta para datos específicos del widget y content para resúmenes visibles del modelo.
  • Formato de dirección: use instrucciones en el manifiesto del agente declarativo para guiar cómo se estructuran y presentan las respuestas.

Problemas de autenticación

Error de coincidencia del identificador de aplicación entre la configuración de autenticación y el complemento

Si ve errores en la tarjeta de información de depuración similares a:

OAuth authentication failed: The App ID used in the request does not match the App ID in the authentication configuration. (HTTP 404)

Vaya al portal para desarrolladores de Teams. Busque el registro de cliente o inicio de sesión único (SSO) de OAuth y compruebe que el identificador de aplicación del complemento coincide con el identificador de aplicación registrado.

La dirección URL base en la configuración de autenticación no coincide con el complemento.

Si ve errores en la tarjeta de información de depuración similares a:

OAuth authentication failed: The base URL in your authentication configuration does not match the server URL. (HTTP 401)

Vaya al portal para desarrolladores de Teams. Busque el registro de cliente de OAuth o sso y compruebe que la dirección URL del servidor MCP del complemento coincide con la dirección URL base registrada.

El identificador de referencia en el manifiesto del complemento es incorrecto o falta

Si ve errores en la tarjeta de información de depuración similares a:

OAuth authentication failed: No matching configuration found for referenceID in 'runtime.auth' section of the action manifest

Vaya al portal para desarrolladores de Teams. Busque el registro de cliente de OAuth o sso y compruebe que el identificador del entorno de ejecución del auth.reference_id servidor MCP coincide con el identificador del registro en el portal para desarrolladores.

La directiva de la organización restringe el acceso

Si ve errores en la tarjeta de información de depuración similares a:

OAuth authentication failed: Access is restricted by your organization's policy. (HTTP 404)

Póngase en contacto con los administradores de la organización para revisar y habilitar el acceso a la aplicación.

El botón Iniciar sesión está inactivo o muestra un error general

Si el botón de inicio de sesión está inactivo o deshabilitado, o si al seleccionarlo se produce un error general "No se puede procesar la solicitud", esta condición podría indicar problemas de autenticación temporal o de sesión. Vuelva a intentar la consulta. Si el problema continúa, vuelva a instalar la aplicación o póngase en contacto con los administradores de la organización.

No se puede abrir la ventana emergente de inicio de sesión

Habilite los elementos emergentes del sitio en la configuración del explorador e inténtelo de nuevo.

Se abre la ventana emergente de inicio de sesión, pero se bloquea o nunca se cierra

Si se abre el elemento emergente de inicio de sesión y el usuario completa la autenticación, pero el elemento emergente nunca se cierra y Copilot no recibe el resultado de autenticación, es probable que la referencia del window.opener elemento emergente se haya destruido durante la cadena de redireccionamiento de OAuth. Sin window.opener, el elemento emergente no puede comunicar el resultado de la autenticación a Copilot. Un síntoma común es que el inicio de sesión produce un error la primera vez, pero se realiza correctamente al reintentar, ya que las credenciales almacenadas en caché omiten la página que destruyó window.opener.

Compruebe los siguientes elementos en la cadena de redireccionamiento de OAuth.

  • Anulación de window.openerJavaScript: algunas páginas de inicio de sesión se establecen window.opener = null como una medida de seguridad general frente a la tabulación inversa. Si alguna página de la cadena de redireccionamiento de autenticación ejecuta este código, el elemento emergente pierde su conexión con Copilot. Las protecciones de tabulación de ámbito solo para la navegación iniciada por el usuario y no se borran window.opener durante las redireccionamientos en elementos emergentes.
  • Cross-Origin-Opener-Policy header establecido same-originen : si alguna página de la cadena de redireccionamiento sirve un Cross-Origin-Opener-Policy: same-origin encabezado de respuesta, el explorador invierte permanentemente la referencia en la window.opener navegación entre orígenes. Asegúrese de que todas las páginas de la cadena de redireccionamiento de OAuth omiten el Cross-Origin-Opener-Policy encabezado (que tiene como valor predeterminado unsafe-none) o lo establecen explícitamente en unsafe-none.
  • Vínculos que usan rel="noopener": Etiquetas de anclaje con rel="noopener" la franja window.opener de la página de destino. No use para la rel="noopener" navegación dentro del elemento emergente de autenticación.

Para depurar este problema, abra las herramientas de desarrollo del explorador en la ventana emergente y escriba window.opener la consola en cada paso de la cadena de redireccionamiento. Si window.opener devuelve null antes de la redirección final, identifique qué página la ha borrado. También puede comprobar los encabezados de respuesta de la pestaña Red en busca Cross-Origin-Opener-Policy de valores en cada página de la cadena.

Error de credenciales incorrecto

Si ve un error de "Credenciales incorrectas" en la respuesta emergente o de chat de inicio de sesión, asegúrese de escribir las credenciales correctas. Si el error persiste, asegúrese de que el usuario tiene los permisos necesarios.

No se encontró la dirección URL de inicio de sesión

Desinstale y vuelva a instalar la aplicación e intente iniciar sesión de nuevo.

Error interno del servidor durante la autenticación

Compruebe los detalles en el elemento emergente de autenticación y póngase en contacto con los administradores de la organización para ver si hay problemas de permisos.

Si aparece un cuadro de diálogo de consentimiento solicitando permisos o justificación empresarial, revise los permisos solicitados y proporcione una justificación empresarial si es necesario. Si no está seguro o si el cuadro de diálogo de consentimiento solicita permisos que requieren consentimiento del administrador, póngase en contacto con los administradores de la organización.

Contenido relacionado

  • Last updated on