Introducción
MCP (Model Context Protocol) es un protocolo abierto desarrollado por Anthropic que permite a Claude Code conectarse con herramientas externas y fuentes de datos a través de una capa estandarizada. En lugar de trabajar únicamente con archivos en un proyecto, una vez integrado un servidor MCP, Claude Code puede consultar bases de datos, llamar a APIs internas, leer documentación de Confluence o ejecutar comandos del sistema — todo dentro de la misma sesión de trabajo.
Esta lección te guía a través de la conexión de un servidor MCP real y luego resume las mejores prácticas y los errores comunes al operar Claude Code en un proyecto real.
Conexión de un servidor MCP
Claude Code gestiona los servidores MCP mediante el comando claude mcp. Existen dos ámbitos de configuración: local (solo para el proyecto actual, almacenado en .claude/settings.json) y global (compartido entre todos los proyectos, almacenado en la configuración del usuario).
Ejemplo de cómo añadir un servidor MCP que se ejecuta vía stdio — el tipo más común cuando el servidor es un proceso que corre en tu máquina:
Después de añadirlo, verifica que el servidor ha sido reconocido:
Para un servidor MCP que se ejecuta vía SSE (Server-Sent Events) — típicamente usado cuando el servidor ya está desplegado en un endpoint HTTP:
Cuando el servidor requiere variables de entorno (por ejemplo, claves de API, cadenas de conexión), pásalas usando el flag -e:
Una vez configurado, reinicia Claude Code. Durante una sesión, Claude detectará y usará automáticamente las herramientas expuestas por el servidor — no necesitas llamarlas manualmente; simplemente describe tu requisito en lenguaje natural y Claude seleccionará la herramienta adecuada.
Depuración de conexiones MCP
Una conexión MCP fallida suele deberse a uno de unos pocos problemas que se pueden comprobar rápidamente.
El servidor MCP no inicia: Ejecuta el comando del servidor directamente fuera de Claude para ver el error raíz. Por ejemplo, si usas npx, ejecútalo manualmente en la terminal para confirmar que el paquete existe y no reporta errores de dependencias.
Claude no ve la herramienta: Usa el comando para comprobar el estado del servidor:
Si el servidor reporta un estado de error, visualiza los logs detallados añadiendo una variable de entorno al ejecutar Claude:
Sintaxis inválida en settings.json: El archivo .claude/settings.json debe ser JSON válido. Las comas finales o la falta de corchetes impedirán que se cargue toda la configuración. Valida el archivo antes de ejecutarlo:
Las variables de entorno no se están pasando: Ten en cuenta que las variables proporcionadas mediante el flag -e al añadir un servidor se almacenan en texto plano en settings.json. No subas este archivo al repositorio si contiene secretos. Usa .gitignore para excluir .claude/settings.json del repositorio.
Mejores prácticas para proyectos reales
Los siguientes principios provienen de la experiencia en proyectos reales, no de la teoría.
Escribe CLAUDE.md desde el principio y mantenlo actualizado. Este archivo es la memoria a largo plazo de Claude sobre el proyecto. Documenta claramente: cómo ejecutar las pruebas, convenciones de nombrado, archivos que no deben modificarse y decisiones arquitectónicas importantes. Claude lee este archivo al inicio de cada sesión — cuanto más específico sea, menos suposiciones incorrectas hará Claude.
Usa git como red de seguridad. Antes de cada tarea importante, asegúrate de que el árbol de trabajo esté limpio. Después de que Claude haga cambios, revisa el diff antes de hacer commit. Claude Code puede crear commits automáticamente si se lo pides, pero usa siempre mensajes de commit significativos:
Mantén el alcance de cada tarea pequeño y claro. En lugar de decir "refactoriza todo el módulo de auth", divídelo en "extrae la lógica de validación del token en una función separada en auth/token.js". Un alcance reducido ayuda a Claude a mantenerse enfocado, facilita la revisión y simplifica el rollback si algo sale mal.
Usa subagentes y /clear en el momento adecuado. La ventana de contexto tiene límites — cuando una sesión abarca muchos archivos y tareas diversas, usa /clear para reiniciar el contexto antes de comenzar una nueva tarea. Esto evita que Claude se vea influenciado por contexto obsoleto que ya no es relevante.
Verifica los resultados con pruebas automatizadas, no solo con inspección visual. Después de cada cambio de código, ejecuta la suite de pruebas. Si el proyecto aún no tiene pruebas, esta es una buena oportunidad para pedirle a Claude que escriba las pruebas antes de escribir la implementación.
Errores comunes que debes evitar
Asignar tareas vagas y esperar resultados precisos. Claude hará su mejor conjetura — pero su conjetura no necesariamente coincidirá con tu intención. Proporciona suficiente contexto: qué archivos están involucrados, cómo debe verse el resultado deseado y qué restricciones deben respetarse.
Permitir que Claude modifique archivos libremente sin controles de permisos adecuados. Si usas el modo desatendido (--dangerously-skip-permissions o CI headless), limita el alcance mediante el archivo CLAUDE.md o mediante tareas claramente estructuradas. Nunca uses este flag en un entorno de producción.
Olvidar que los servidores MCP pueden exponer información sensible. Cuando un servidor se conecta a una base de datos o a una API interna, Claude puede leer datos reales. Restringe los permisos de la cuenta de servicio utilizada por el servidor MCP al mínimo necesario.
Copiar la salida de Claude directamente a producción sin leerla. El código generado por IA puede ser lógicamente correcto pero defectuoso desde la perspectiva de seguridad, o puede pasar por alto casos extremos. La revisión de código es obligatoria, no opcional.
Resumen
Los servidores MCP son el puente que permite a Claude Code ir más allá de los archivos de código puro e interactuar con la infraestructura real de un proyecto. Conectar correctamente, depurar de forma sistemática y usar el modo de transporte adecuado son los cimientos para una integración estable. Más allá de eso, prácticas como mantener CLAUDE.md, mantener el alcance de las tareas pequeño y siempre revisar antes de hacer commit no son un mero trámite — son las condiciones que hacen que Claude Code sea genuinamente útil en lugar de generarte más trabajo.
Punto de control de la lección
Repasa lo aprendido y recibe comentarios sobre tu trabajo.