Aprende a gestionar fallas de forma elegante: validación, try/except, timeouts y logging.
Los Servers MCP están sujetos a diversos tipos de fallas. Comprender cada categoría de error es el primer paso para tratarlos adecuadamente. Un buen server no es aquel que nunca falla, sino aquel que falla de forma predecible, informativa y recuperable.
Los errores en un server MCP se dividen en cuatro categorías principales: errores de entrada (parámetros inválidos, tipos incorrectos, valores fuera del rango esperado); errores de ejecución (errores en el código, división entre cero, clave inexistente en un diccionario); errores de red (API externa fuera de servicio, timeout de conexión, DNS no resuelto); y errores de permisos (acceso denegado a un archivo, token vencido, credenciales no válidas). Cada tipo requiere una estrategia de manejo diferente.
Los estudios de ingeniería de software muestran que más del 60% de los incidentes en producción se deben a un manejo inadecuado de errores, no a los errores en sí. En servers MCP, esto es aún más crítico porque el modelo de IA depende de mensajes de error claros para informar al usuario sobre lo ocurrido y sugerir los siguientes pasos. Un stack trace sin procesar no ayuda a nadie.
Parámetros no válidos, tipos incorrectos, valores fuera del rango. Se pueden detectar antes de ejecutar la lógica principal. Se previenen con validación.
Errores en el código, KeyError, IndexError y división por cero. Ocurren durante el procesamiento. Se previenen con try/except y pruebas.
API fuera de servicio, timeout, DNS no resuelto. Son imprevisibles y transitorios. Se manejan con reintentos y mensajes claros.
Acceso denegado, token vencido, credenciales no válidas. Requieren una acción del usuario o del administrador. Mensaje claro sobre lo que falta.
La primera línea de defensa contra errores es la validación de entradas. Antes de procesar cualquier dato, verifica que los parámetros sean correctos: tipo, formato, rango y presencia. Nunca confíes en los datos que recibes. Devuelve mensajes claros cuando algo esté mal para que el modelo pueda informar al usuario de forma útil.
Una validación sólida al inicio de la tool evita errores en cascada:
Nunca expongas datos sensibles en mensajes de error. Evita devolver rutas de archivos del servidor, nombres de variables de entorno, cadenas de conexión a bases de datos o cualquier información que pueda usarse para explotar el sistema. Los mensajes de error deben ser útiles para el usuario, no para un atacante.
Incluso con una validación perfecta, pueden ocurrir errores de ejecución. La estructura try/except es tu red de seguridad: captura excepciones antes de que hagan caer el server y permite devolver mensajes de error útiles en lugar de stack traces incomprensibles.
Envuelve la lógica principal en try/except con excepciones específicas:
Siempre captura las excepciones específicas antes que la genérica. Empieza con los errores más probables (ValueError, KeyError, json.JSONDecodeError) y termina con except Exception como red de seguridad final. Nunca uses except: sin tipo: esto captura incluso KeyboardInterrupt y SystemExit.
except: sin tipo de excepciónpassCuando tus tools hacen solicitudes HTTP a APIs externas, los fallos de red son inevitables. El servidor de la API puede estar fuera de servicio, la conexión puede agotar el tiempo de espera o la respuesta puede tener un estado de error. Cada tipo de fallo de red requiere un manejo específico, con mensajes que ayuden al modelo a informar al usuario qué ocurrió.
Con httpx, los principales errores de red son:
httpx.ConnectError — no se pudo conectar al servidor (DNS, puerto cerrado, host inaccesible)httpx.TimeoutException — se agotó el tiempo límite de conexión o lecturahttpx.HTTPStatusError — el servidor respondió con estado 4xx o 5xxManeja cada uno por separado para darle mensajes precisos al modelo.
Servidor inaccesible. Mensaje: "No se pudo conectar al servicio X. Verifica si el servicio está en línea." Reintentar puede ayudar si el problema es transitorio.
Tiempo agotado. Mensaje: "La solicitud al servicio X tardó más de lo esperado." Considera aumentar el timeout o reintentar con backoff.
Respuesta con error. 404 = recurso no encontrado, 401/403 = no autorizado, 500 = error en el servidor externo. Adapta el mensaje al status code.
Ten cuidado con los reintentos infinitos. Si la API está fuera de servicio, intentar de nuevo sin límites bloqueará tu tool. Usa retry con backoff exponencial y un máximo de intentos (p. ej., 3 intentos con esperas de 1s, 2s, 4s). Si todos fallan, devuelve un mensaje claro que indique que el servicio no está disponible temporalmente.
Configurar timeouts es esencial en los servers MCP. El modelo de IA espera la respuesta de la tool para continuar: si la tool se bloquea en una solicitud HTTP sin timeout, el modelo queda esperando indefinidamente. Define siempre límites de tiempo para las operaciones que pueden tardar.
Siempre configura un timeout en las solicitudes HTTP:
El valor timeout=10.0 significa que la solicitud se cancelará si tarda más de 10 segundos. Para API rápidas, 5-10 segundos es suficiente. Para operaciones pesadas, pueden ser necesarios 30 segundos o más, pero siempre con un límite definido.
Puedes configurar timeouts granulares con httpx.Timeout(connect=5.0, read=10.0, write=5.0, pool=5.0). Esto permite distintos límites para la conexión, la lectura, la escritura y el pool. En la mayoría de los casos, timeout=10.0 como valor único es suficiente y más fácil de mantener.
Los mensajes de error que se devuelven al modelo deben ser simples y útiles. Pero tú, como desarrollador, necesitas todos los detalles para diagnosticar problemas. Ahí es donde entra el logging: registrar errores detallados en stderr sin interferir con el protocolo MCP que usa stdout.
Configura el logging para registrar errores detallados en stderr:
O exc_info=True incluye el stack trace completo en el log, algo esencial para depurar. El protocolo MCP usa stdout para la comunicación, así que los logs en stderr no interfieren.
Usa niveles de log adecuados: DEBUG para detalles de desarrollo, INFO para operaciones normales (tool invocada, parámetros recibidos), WARNING para situaciones sospechosas, pero no críticas, ERROR para fallas que impiden el funcionamiento. En producción, configura el nivel en INFO; en desarrollo, usa DEBUG.
MCP Inspector muestra los logs del server en su interfaz, lo que facilita la depuración durante el desarrollo. Los logs estructurados (con timestamp, nivel y nombre del logger) son 3 veces más rápidos de diagnosticar que los prints sueltos, según estudios de ingeniería de software. Dedica tiempo a configurar correctamente el logging desde el principio: lo agradecerás cuando aparezca el primer bug en producción.
Siguiente Módulo: 3.9 — Probando con MCP Inspector