Solución de problemas

Cómo diagnosticar problemas

Si un componente no se muestra, el mecanismo de descubrimiento pasa por alto algunos prompts o la autenticación entra en un bucle, empieza por identificar en qué capa se origina el problema: el servidor, el componente o el cliente de ChatGPT. La siguiente lista de verificación incluye los problemas más comunes y cómo resolverlos.

Las comprobaciones del servidor, las herramientas y el mecanismo de descubrimiento se aplican a los complementos de ChatGPT y Codex. Las comprobaciones de la interfaz de usuario, el estado de los widgets y la autenticación del cliente que se describen en esta página corresponden a ChatGPT.

Problemas del servidor

• No aparece ninguna herramienta: comprueba que tu servidor esté en ejecución y que te estés conectando al punto de acceso /mcp. Si cambiaste de puerto, actualiza la URL del servidor MCP y reinicia MCP Inspector.
• Solo aparece el contenido estructurado, sin el componente: comprueba que, en el descriptor de la herramienta, _meta.ui.resourceUri apunte a un recurso HTML registrado con mimeType: "text/html;profile=mcp-app" (ChatGPT admite _meta["openai/outputTemplate"] como alias opcional por compatibilidad) y que el recurso se cargue sin errores de CSP.
• Errores de incompatibilidad con el esquema: asegúrate de que tus modelos de Python o TypeScript coincidan con el esquema declarado en outputSchema. Vuelve a generar los tipos después de hacer cambios.
• Respuestas lentas: los componentes tardan en responder cuando las llamadas a herramientas demoran más de unos cientos de milisegundos. Mide el rendimiento de las llamadas al servidor y guarda los resultados en caché cuando sea posible.

Problemas con los widgets

• El widget no se carga: abre la consola del navegador (o los registros de MCP Inspector) y busca infracciones de la CSP o paquetes faltantes. Asegúrate de que el HTML incluya tu JavaScript compilado y de que el paquete contenga todas las dependencias.
• No se guardan los cambios al arrastrar y soltar elementos o al editarlos: si usas ChatGPT para guardar el estado del widget, llama a window.openai.setWidgetState después de cada actualización y restaura el estado a partir de window.openai.widgetState al montar el widget.
• Problemas de diseño en dispositivos móviles: si usas las señales de diseño de ChatGPT, revisa window.openai.displayMode y window.openai.maxHeight para ajustar el diseño. Evita las alturas fijas y las acciones que solo están disponibles al pasar el cursor sobre un elemento.

Problemas de descubrimiento y puntos de entrada

• La herramienta nunca se activa: revisa sus metadatos. Reformula las descripciones con frases como “Usa esta herramienta cuando…”, actualiza los prompts iniciales y repite las pruebas con tu conjunto de prompts de referencia.
• Se selecciona la herramienta equivocada: agrega detalles que permitan distinguir las herramientas similares o especifica en la descripción en qué casos no se permite usar la herramienta. Considera dividir las herramientas grandes en otras más pequeñas, cada una con un propósito específico.
• El orden en el lanzador parece incorrecto: actualiza los metadatos del complemento en el directorio y comprueba que el ícono y las descripciones coincidan con lo que esperan los usuarios.

Problemas de autenticación

• Errores 401: incluye el encabezado WWW-Authenticate en la respuesta de error para indicarle a ChatGPT que debe reiniciar el flujo de OAuth. Vuelve a verificar las URL del emisor y las declaraciones de audiencia.
• Falla el registro del cliente: si usas CIMD, comprueba que los metadatos de tu servidor de autorización incluyan client_id_metadata_document_supported: true y que el servidor pueda obtener el documento de metadatos del cliente de ChatGPT. Si usas private_key_jwt, comprueba que tu servidor de autorización pueda obtener el JWKS público de ChatGPT y verificar la aserción firmada del cliente. Si usas DCR, comprueba que tu servidor de autorización exponga registration_endpoint y que los clientes recién creados tengan habilitada al menos una conexión de inicio de sesión.
• Una conexión existente a un servidor MCP devuelve invalid_client: comprueba que el cliente OAuth registrado dinámicamente aún exista y que tu servidor de autorización acepte el secreto del cliente, si tiene uno. ChatGPT reutiliza estas credenciales, así que restáuralas en lugar de crear un cliente nuevo. Si el token de acceso venció, la solución es otra.

Problemas de despliegue

• Se agota el tiempo de espera del túnel de ngrok: reinicia el túnel y comprueba que tu servidor local esté en ejecución antes de compartir la URL. En producción, usa un proveedor de alojamiento estable que ofrezca comprobaciones de estado.
• La transmisión se interrumpe al pasar por un proxy: asegúrate de que tu balanceador de carga o CDN permita los eventos enviados por el servidor o las respuestas HTTP en streaming sin almacenarlos en un búfer.

Cuándo escalar un problema

Si ya verificaste los puntos anteriores y el problema persiste:

1. Recopila los registros del servidor y de la consola del componente, la transcripción de la llamada a la herramienta en ChatGPT y capturas de pantalla.
2. Anota el prompt que enviaste y los mensajes de confirmación que hayas recibido.
3. Comparte los detalles con tu contacto para socios de OpenAI para que pueda reproducir el problema internamente.

Un registro claro del problema y de las comprobaciones realizadas reduce el tiempo de resolución y ayuda a que tu servidor MCP siga siendo confiable para los usuarios.