- Diagnóstico de fallos de red, DNS y configuración de rutas en entornos de nube y locales.
- Resolución de conflictos de autenticación mediante tokens OAuth y claves de API.
- Ajustes técnicos en transportes HTTP, SSE y stdio para garantizar la interoperabilidad.
- Optimización de la configuración en clientes como Claude Desktop, Claude Code y Cursor.
Seguro que te ha pasado: tienes todo listo para potenciar tu flujo de trabajo con la IA, pero al intentar conectar un servidor MCP, el sistema te suelta un error críptico y no sabes por dónde empezar. El Protocolo de Contexto de Modelo es una herramienta brutal para que modelos como Claude interactúen con tus bases de datos o archivos locales, pero la configuración inicial puede ser un auténtico quebradero de cabeza si no conoces los puntos críticos.
No te preocupes, que no es magia negra ni tienes que ser un gurú de la infraestructura para arreglarlo. La mayoría de los fallos se deben a detalles insignificantes en los archivos JSON, puertos mal mapeados o tokens que han caducado sin avisar. En este artículo vamos a destripar cada uno de los problemas más habituales, desde despliegues en la nube de Azure hasta configuraciones locales en macOS o Windows, para que dejes de pelearte con la consola y empieces a producir.
Problemas de acceso y red en entornos de nube
Cuando montamos servidores MCP en Azure Container Apps, es muy común que el cliente simplemente no encuentre el servidor. Si te encuentras con un tiempo de espera agotado o errores de DNS en VS Code o GitHub Copilot, lo primero es mirar la configuración de entrada. Si el acceso no está marcado como external, el servidor será invisible para el mundo exterior.
Otro escollo típico es el FQDN incorrecto. No te fíes de la memoria; lo mejor es ejecutar la consulta de Azure para verificar el nombre de host real. Además, si usas dominios propios, revisa que el certificado TLS esté bien enlazado, ya que un error de seguridad bloqueará la conexión al instante.
En cuanto a los firewalls, asegúrate de que el puerto 443 (HTTPS) esté abierto para las direcciones de azurecontainerapps.io. Si el servidor responde con un error 404, revisa la ruta del punto de conexión. En Python con FastMCP, hay un error muy frecuente: montar la app en /mcp en lugar de en /, lo que provoca que la ruta final sea /mcp/mcp y, por supuesto, no funcione.
Fallos de protocolo, transporte y CORS
A veces la conexión existe, pero el servidor y el cliente «hablan idiomas distintos». Si recibes un error de código -32601 (Método no encontrado), es probable que estés intentando llamar a una herramienta sin haber ejecutado primero la fase de initialize. El protocolo JSON-RPC es muy estricto: primero se saludan y luego se pide la información.
El transporte es otro punto débil. Las versiones actuales de MCP utilizan principalmente stdio y Streamable HTTP, mientras que el antiguo transporte HTTP+SSE aparece todavía en servidores y ejemplos anteriores. Con Streamable HTTP, el cliente envía los mensajes mediante solicitudes POST y el servidor puede responder con JSON o con un flujo SSE. Si el cliente y el servidor utilizan transportes incompatibles, pueden aparecer errores 404, 405 o respuestas con un tipo de contenido inesperado.
Para quienes desarrollan clientes basados en el navegador, el CORS es la pesadilla de siempre. Si ves el mensaje de bloqueo de política CORS en la consola, tendrás que actualizar la configuración de ingreso de tu aplicación para permitir los dominios específicos y los encabezados necesarios, como Mcp-Session-Id.
Errores de autenticación y seguridad
El error 401 Unauthorized es el pan nuestro de cada día. Dependiendo de dónde esté alojado el servidor, la solución varía. En aplicaciones independientes, revisa que el token de portador (Bearer Token) sea válido y que el audience en Microsoft Entra coincida con el recurso solicitado. Si estás usando sesiones dinámicas, recuerda que la clave API debe ir en el encabezado x-ms-apikey y no en el de Authorization.
En el caso de bases de datos de IA autónomas, el problema suele estar en el punto final de autenticación. Es vital no confundir la URL donde se piden los tokens OAuth con la URL donde se procesan las herramientas del agente. Si el token ha caducado (suelen durar una hora), tendrás que generar uno nuevo y actualizar el archivo de configuración.
Si aparece un mensaje de «cliente no válido» durante la autorización, revisa primero los registros del cliente y elimina la conexión guardada desde sus ajustes para iniciar de nuevo el proceso OAuth. Algunos clientes almacenan las sesiones en carpetas locales propias, pero la ubicación cambia según la aplicación y el sistema operativo; consulta su documentación antes de borrar archivos de autenticación manualmente.
Configuración de clientes: Claude Desktop, Code y Cursor
Configurar Claude Desktop puede hacerse de dos formas. La más sencilla es el directorio de extensiones, donde instalas todo con un clic. Pero si vas por la ruta manual del JSON, necesitas tener Node.js instalado. Si el servidor no arranca, verifica que las rutas en el archivo claude_desktop_config.json sean absolutas; usar rutas relativas es una receta para el desastre.
En Cursor, la lógica es similar a Claude Code pero se gestiona a través del archivo .cursor/mcp.json. Un fallo típico es olvidar las variables de entorno en la sección env; si el servidor necesita una API Key de Google Maps o Brave Search y no está ahí, el servidor se iniciará pero la lista de herramientas aparecerá vacía, algo común al usar agentes en Cursor.
Diagnóstico avanzado y resolución de problemas
Cuando nada de lo anterior funciona, toca sacar la artillería pesada. Antes de abrir un ticket de soporte, prueba el servidor con curl en la terminal. Envía una solicitud de initialize y una de tools/list. Si el servidor devuelve un JSON-RPC válido, el problema no está en el servidor, sino en la configuración de tu cliente (Claude o Cursor).
Si usas GitHub Copilot como cliente, no ignores el panel de salida. Ve a Ver > Salida y selecciona GitHub Copilot Chat – MCP. Allí verás los registros reales de conexión y podrás distinguir si el fallo es por un timeout, un error de red o una respuesta 400 del servidor.
En el despliegue de contenedores, evita que el servidor se reinicie constantemente debido a las comprobaciones de estado (health probes). Los sondeos de Azure suelen enviar GET, pero los servidores MCP esperan POST. La solución es crear un punto de conexión GET /health dedicado que simplemente devuelva un 200 OK para engañar al sistema de monitoreo.
Tener el control total de la conexión implica dominar desde la limpieza de cachés en .mcp_auth hasta la gestión de puertos y la correcta implementación de transportes. Ya sea que estés peleando con un puerto 8080 mal mapeado o un token de OAuth expirado, la clave está en verificar cada capa: red, autenticación, protocolo y finalmente la configuración del cliente.
Soy un apasionado de la tecnología que ha convertido sus intereses «frikis» en profesión. Llevo más de 10 años de mi vida utilizando tecnología de vanguardia y trasteando todo tipo de programas por pura curiosidad. Ahora me he especializado en tecnología de ordenador y videojuegos. Esto es por que desde hace más de 5 años que trabajo redactando para varias webs en materia de tecnología y videojuegos, creando artículos que buscan darte la información que necesitas con un lenguaje entendible por todos.
Si tienes cualquier pregunta, mis conocimientos van desde todo lo relacionado con el sistema operativo Windows así como Android para móviles. Y es que mi compromiso es contigo, siempre estoy dispuesto a dedicarte unos minutos y ayudarte a resolver cualquier duda que tengas en este mundo de internet.