Solución de problemas

Cómo diagnosticar problemas

Cuando algo falla, ya sea que los componentes no se rendericen, que la detección no reconozca ciertos prompts o que la autenticación entre en un bucle, empieza por identificar la capa responsable: el servidor, el componente o el cliente de ChatGPT. La siguiente lista de verificación abarca los problemas más comunes y cómo resolverlos.

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

Problemas del lado del servidor

• No aparecen herramientas: confirma que tu servidor esté en ejecución y que te estés conectando al punto de acceso /mcp. Si cambiaste los puertos, actualiza la URL del servidor MCP y reinicia MCP Inspector.
• Solo aparece contenido estructurado, sin componente: confirma que el descriptor de la herramienta establezca _meta.ui.resourceUri en un recurso HTML registrado con mimeType: "text/html;profile=mcp-app" (ChatGPT admite _meta["openai/outputTemplate"] como alias opcional de compatibilidad) y que el recurso se cargue sin errores de CSP.
• Errores de discrepancia de 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 se sienten lentos cuando las llamadas a herramientas tardan más de unos cientos de milisegundos. Analiza el rendimiento de las llamadas al servidor y almacena 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) para buscar infracciones de CSP o paquetes faltantes. Asegúrate de que el HTML contenga tu JavaScript compilado y de que el paquete incluya todas las dependencias.
• Los cambios al arrastrar y soltar o editar no se conservan: si usas la persistencia del estado de widgets de ChatGPT, llama a window.openai.setWidgetState después de cada actualización y restaura el estado desde window.openai.widgetState al montar el componente.
• Problemas de diseño en dispositivos móviles: si usas las señales de diseño de ChatGPT, inspecciona window.openai.displayMode y window.openai.maxHeight para ajustar el diseño. Evita las alturas fijas y las acciones que solo se activan al pasar el cursor.

Problemas de detección y puntos de entrada

• La herramienta nunca se activa: revisa tus metadatos. Reescribe las descripciones con frases como “Usa esta herramienta cuando…”, actualiza los prompts iniciales y vuelve a probar con tu conjunto de prompts de referencia.
• Se selecciona la herramienta incorrecta: agrega detalles que permitan distinguir las herramientas similares o especifica en la descripción los escenarios no permitidos. Considera dividir las herramientas grandes en otras más pequeñas y diseñadas para fines específicos.
• El orden en el iniciador no parece correcto: actualiza tus metadatos del directorio y asegúrate de que el ícono y las descripciones del complemento coincidan con lo que esperan los usuarios.

Problemas de autenticación

• Errores 401: incluye un encabezado WWW-Authenticate en la respuesta de error para que ChatGPT sepa que debe volver a iniciar el flujo de OAuth. Revisa las URL del emisor y las declaraciones de audiencia.
• Falla el registro del cliente: si usas CIMD, confirma 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. Para private_key_jwt, confirma 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, confirma que tu servidor de autorización exponga registration_endpoint y que los clientes recién creados tengan al menos una conexión de inicio de sesión habilitada.
• Una conexión existente a un servidor MCP devuelve invalid_client: confirma que el cliente OAuth registrado dinámicamente siga existiendo y que tu servidor de autorización acepte su secreto de cliente, si tiene uno. ChatGPT reutiliza estas credenciales, así que restáuralas en lugar de crear un cliente nuevo. Un token de acceso vencido requiere una solución diferente.

Problemas de despliegue

• Se agota el tiempo de espera del túnel de ngrok: reinicia el túnel y verifica que tu servidor local esté en ejecución antes de compartir la URL. Para producción, usa un proveedor de alojamiento estable con comprobaciones de estado.
• La transmisión continua falla detrás de proxies: asegúrate de que tu balanceador de carga o CDN permita eventos enviados por el servidor o respuestas HTTP de transmisión continua sin almacenamiento en búfer.

Cuándo escalar el problema

Si ya verificaste los puntos anteriores y el problema persiste:

1. Recopila registros (del servidor, de la consola del componente y de las llamadas a herramientas de 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 de alianzas en OpenAI para que pueda reproducir el problema internamente.

Un registro claro y conciso de la solución de problemas reduce el tiempo de resolución y mantiene la confiabilidad de tu servidor MCP para los usuarios.