Hola, soy Lena. MCP ya no es un concepto nuevo, pero en realidad conectar un servidor dentro de Claude Code sin tener problemas es más matizado de lo que la mayoría de la gente espera.
He estado usando Claude Code con varios servidores MCP para mi desarrollo diario durante los últimos meses — de todo, desde GitHub hasta Sentry y herramientas personalizadas internas de consulta de bases de datos. Honestamente, la configuración en sí misma no es difícil — la parte difícil es averiguar en qué confiar, dónde mirar cuando OAuth falla y cómo funciona realmente el alcance. Este artículo es una colección concentrada de los problemas que he encontrado y los detalles oficiales que he rastreado, escrito para desarrolladores que ya usan Claude Code y están listos para conectar servidores MCP.
Prerrequisitos antes de conectar servidores MCP
Versión de Claude Code y soporte de plataforma
Comienza verificando tu versión. Los comportamientos relacionados con OAuth solo se estabilizaron después de v2.1.64 — fue entonces cuando se introdujo el soporte authServerMetadataUrl. Las versiones antiguas lanzarán errores al autenticarse con servidores remotos. También hay un inconveniente conocido en Windows: claude mcp add-json ocasionalmente devuelve "Entrada inválida" al agregar servidores HTTP. La documentación oficial de MCP recomienda recurrir al formato claude mcp add --transport http si te encuentras con este problema.
Lo que MCP puede hacer realmente dentro de Claude Code
MCP transforma Claude Code de una herramienta que solo puede leer y escribir archivos locales y ejecutar comandos bash en un agente que puede interactuar directamente con sistemas externos — obtener tickets de Jira, crear PRs en GitHub, consultar Sentry para errores de producción, lo que sea. Pero aquí hay un detalle que a menudo se pasa por alto: los servidores MCP están completamente aislados entre sí. No hay paso a través — cada capa es independiente.
Herramientas, recursos y prompts
Según la especificación de MCP, un servidor puede exponer tres tipos de capacidades: herramientas (acciones ejecutables), recursos (fuentes de datos legibles), y prompts (plantillas de interacción predefinidas). El panel /mcp muestra el conteo de herramientas para cada servidor conectado, y marca cualquier servidor que declare la capacidad de herramientas pero que en realidad no exponga ninguna.
Paso a paso: agregando tu primer servidor MCP
Agregar un servidor mediante la CLI
Claude Code soporta tres tipos de transporte: HTTP (recomendado para servicios remotos), SSE (obsoleto — evitar si es posible), y stdio (procesos locales).
# Remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp
# Local stdio server
claude mcp add --transport stdio --env API_KEY=your_key myserver \
-- npx -y my-mcp-server
Aquí está el detalle que confunde a la gente: todas las opciones deben ir antes del nombre del servidor. El doble guion -- separa las banderas de Claude de los argumentos pasados al proceso del servidor MCP. Si se coloca en el orden incorrecto, el comando falla silenciosamente. Me ha pasado más de una vez.
Agregar mediante .mcp.json para compartir con el equipo
Usa --scope project para escribir la configuración en un archivo .mcp.json que puedas comprometer al control de versiones. Nunca pongas tokens reales en este archivo — usa referencias a variables de entorno en su lugar. Las configuraciones de ámbito local sobrescriben las de ámbito de proyecto para servidores con el mismo nombre, lo que mantiene privadas las credenciales.
Verificando que el servidor esté conectado
Ejecuta /mcp dentro de Claude Code para comprobar el estado y el conteo de herramientas. Los servidores HTTP/SSE reintentan automáticamente las conexiones iniciales hasta tres veces a partir de la versión v2.1.121, pero los errores de autenticación y los 404 no se reintentan — esos requieren un cambio en la configuración.
Aprobando herramientas en el primer uso
La primera vez que invocas una herramienta desde un servidor nuevo, Claude Code pedirá permiso. Esto es verificación de confianza por diseño. La documentación de seguridad de Claude Code indica explícitamente que los nuevos servidores MCP requieren confirmación del usuario. Puedes aprobar una vez o elegir "Permitir siempre" para agregarlo a tu lista de permitidos.
Autenticación y flujo OAuth
Servidores que requieren tokens OAuth
La mayoría de los servidores remotos — GitHub, Slack, Notion y servicios similares — requieren OAuth. Claude Code tiene soporte integrado para OAuth 2.1, y el flujo es en gran parte automático: el servidor devuelve un 401, Claude Code descubre los metadatos OAuth (primero verificando RFC 9728 Protected Resource Metadata, luego regresando a RFC 8414), se registra automáticamente como cliente si se soporta Dynamic Client Registration, abre un navegador para la autorización y obtiene el token.
Cuando un servidor no soporta Dynamic Client Registration, verás un error de "Servidor de autenticación incompatible". En ese caso, registra una aplicación OAuth a través del portal de desarrolladores del servidor, toma el ID de cliente y el secreto, y agrega el servidor usando --client-id y --client-secret. Algunos servidores también requieren un puerto de callback fijo — usa --callback-port para que coincida con el URI de redirección que registraste.
Dónde se almacenan las credenciales y cómo rotarlas
Los tokens se almacenan en el almacenamiento seguro de credenciales de su sistema: macOS Keychain o un archivo de credenciales encriptado en otras plataformas. Nunca se almacenan en archivos de configuración en texto plano. Para rotar credenciales, abra /mcp y vuelva a autenticarse para el servidor correspondiente. En entornos SSH sin navegador, Claude Code muestra un aviso de "Pegar código aquí" para que pueda completar la autorización en otra máquina y pegar el resultado de nuevo.
Evitar fugas de tokens en configuraciones compartidas
Seré directo aquí: he visto más de un equipo subir configuraciones con tokens codificados a repositorios públicos. Siempre use referencias ${ENV_VAR} para las credenciales. En entornos empresariales, los administradores pueden desplegar un archivo managed-mcp.json con políticas de lista de permitidos y lista de denegados para controlar qué servidores pueden ser utilizados.
Límites de seguridad a revisar antes de confiar en un servidor
Lo que un servidor MCP puede leer en su máquina
Un servidor tipo stdio se ejecuta con los permisos de su usuario actual, lo cual es algo en lo que muchos desarrolladores no piensan con suficiente cuidado. En teoría, puede leer su .env, claves SSH y credenciales de AWS — cualquier cosa a la que pueda acceder su cuenta de usuario. Claude Code tiene salvaguardas: las operaciones de escritura están restringidas al directorio de trabajo y las solicitudes de red requieren aprobación. El blog de ingeniería de seguridad de Anthropic detalla el mecanismo de sandbox, que incluye aislamiento tanto del sistema de archivos como de la red trabajando juntos. Sus datos internos muestran que el sandbox reduce las solicitudes de permisos en un 84%, lo cual es significativo para el flujo de trabajo diario.
Lo que puede ejecutar o escribir
Las herramientas MCP pueden incluir capacidades de ejecución arbitraria. Una herramienta de "ejecutar SQL" conectada a una base de datos de producción ejecutará verdaderamente consultas sobre datos de producción. Esto no es hipotético: he visto configuraciones donde una sola herramienta mal configurada tenía acceso de escritura a una base de datos de clientes en vivo. Antes de conectar cualquier servidor, necesita entender exactamente qué herramientas expone y qué puede hacer cada una. Mantenga cualquier cosa de la que no esté seguro en modo de consulta en lugar de aprobar automáticamente.
Revisar el código fuente y mantenimiento antes de la aprobación
Antes de confiar en un servidor, normalmente hago tres cosas: revisar el código fuente (verificar el archivo principal de entrada en GitHub para confirmar lo que realmente hace), evaluar el estado de mantenimiento (un paquete publicado hace 3 días frente a uno mantenido durante 2 años — perfiles de riesgo completamente diferentes), y verificar las declaraciones de permisos (según la especificación de autorización MCP, los servidores deben declarar sus alcances requeridos — atento a cualquier cosa que exceda los límites razonables).
Problemas comunes y cómo solucionarlos
Servidor que no aparece después de agregarlo
La causa más común: alcance incorrecto. Un servidor agregado con --scope local en el directorio del proyecto A no será visible cuando cambies al proyecto B. Usa claude mcp list para confirmar el alcance, y cambia a --scope user si necesitas que esté disponible en todas partes. También vale la pena señalar: workspace es un nombre reservado — usarlo hará que el servidor se omita con una advertencia.
Llamadas a herramientas que fallan silenciosamente
Primero, verifica si la salida excede el límite predeterminado de 10,000 tokens. Claude Code muestra una advertencia cuando esto sucede, pero es fácil pasarlo por alto. Configura MAX_MCP_OUTPUT_TOKENS=50000 para aumentar el límite. Otra posibilidad es una desconexión — los servidores HTTP/SSE se reconectan automáticamente con retroceso exponencial (hasta 5 intentos), pero los servidores stdio no se reconectan automáticamente.
Conflictos de alcance entre configuraciones locales y de proyecto
Cuando existe un servidor con el mismo nombre tanto en el alcance local como en el del proyecto, lo local sobrescribe lo del proyecto. Esto es intencional, pero si no lo sabes, te preguntarás por qué tus cambios en .mcp.json no se están aplicando. Usa claude mcp get <name> para ver qué configuración está activa realmente.
Solicitudes de permisos que se repiten en cada sesión
Si no seleccionaste "Permitir siempre", la aprobación no se mantendrá. Usa /permissions para gestionar tu lista de permisos permanente. El repositorio de GitHub de Claude Code tiene documentación sobre los hooks PreToolUse, que permiten una lógica de aprobación automatizada más detallada.
Dónde la conexión deja de ser suficiente
MCP proporciona herramientas, pero no preserva lo que funcionó
Esta es la limitación que siento más intensamente en el uso diario. MCP resuelve el problema de la "conexión", pero no resuelve el problema de la "memoria". Podrías pasar 20 minutos hoy haciendo que un flujo de trabajo de consulta a base de datos más generación de informes funcione perfectamente, solo para descubrir que la nueva sesión de mañana ha perdido todo ese contexto. Tendrás que volver a explicar qué tablas consultar, en qué formato generar el resultado y qué casos límite manejar. El protocolo MCP no incluye ningún mecanismo de persistencia de sesión. Cada conexión es sin estado. Eso no es un error, es un límite de diseño.
Por qué los equipos todavía repiten correcciones a lo largo de sesiones y máquinas
El desarrollador A descubre la manera correcta de usar un servidor en particular, trabaja en un caso límite y hace que todo funcione sin problemas. Pero ese conocimiento arduamente adquirido no tiene dónde vivir. El desarrollador B se une al proyecto una semana después y se enfrenta exactamente a los mismos problemas, pasando el mismo tiempo depurando los mismos problemas. .mcp.json comparte la configuración, no comparte "cómo usarlo realmente" o "qué se rompió la última vez y cómo lo arreglamos". Los archivos CLAUDE.md pueden mitigar esto parcialmente, pero son estáticos y se mantienen manualmente. MCP hace muy bien lo que hace, pero para flujos de trabajo complejos, eventualmente enfrentarás el problema de la pérdida de contexto y el conocimiento tribal repetido.
Preguntas frecuentes
¿Es MCP lo mismo que un complemento (plugin)?
No exactamente. MCP es un estándar de protocolo abierto que define cómo las aplicaciones de IA se comunican con herramientas externas. Los complementos son un concepto de nivel superior en Claude Code que pueden incluir configuraciones de servidor MCP junto con otros tipos de extensiones. La página de anuncio de Anthropic tiene la publicación original del lanzamiento de MCP.
¿Necesito una clave API para usar los servidores MCP?
Depende del servidor. Los servidores locales stdio normalmente no requieren ninguna autenticación. Los servidores HTTP remotos usualmente necesitan credenciales, ya sea un token Bearer (pasado vía --header) o OAuth (manejados automáticamente).
¿Pueden mis compañeros de equipo ver mis servidores MCP?
Solo las configuraciones --scope project se escriben en .mcp.json y son visibles para tu equipo. Tanto el alcance local (el predeterminado) como el de usuario son privados.
¿Cuál es la diferencia entre alcance local, de proyecto y de usuario?
local (predeterminado): disponible solo para ti en el directorio del proyecto actual. project: escrito en .mcp.json en la raíz del proyecto, compartido con todo el equipo mediante control de versiones. user: disponible para ti en todos los proyectos de tu máquina. Ten en cuenta que en versiones anteriores, local se llamaba "project" y user se llamaba "global" — la nomenclatura se ha actualizado desde entonces, así que no te confundas con publicaciones de blogs o guías antiguas que usan la terminología antigua.
¿Por qué Claude Code sigue pidiendo permiso para la misma herramienta?
Las nuevas sesiones no heredan aprobaciones temporales por defecto. Usa "Permitir siempre" o /permissions para agregar herramientas a tu lista de permitidos permanente. En configuraciones empresariales, las reglas de denegación en managed-settings.json sobrescriben tus reglas de permitir locales, lo que también puede causar rechazos repetidos.
Publicaciones anteriores:
- ¿Quieres un modelo mental más claro de MCP en sí y por qué se está convirtiendo en la capa estándar para las conexiones de herramientas de IA? Lee: Qué es el estándar de conexión de herramientas AI MCP
- Si planeas usar MCP dentro de Claude Code, esta guía práctica de configuración y extensiones se combina naturalmente con el flujo de trabajo discutido arriba: Guía de Configuración y Extensiones de Claude Code MCP
- ¿Curioso sobre cuáles servidores MCP son realmente útiles en el desarrollo diario en lugar de solo para demostraciones? Esta recopilación del mundo real vale la pena guardarla: Servidores MCP más útiles en el mundo real
- MCP maneja conexiones, pero Claude Skills maneja capas de comportamiento reutilizables — esta referencia para desarrolladores explica esa parte de la pila en mucha más profundidad: Referencia de Desarrollador de Claude Code Skills
- La limitación de “conexión vs memoria” mencionada en este artículo conduce directamente a problemas de persistencia local y continuidad de flujo de trabajo explorados aquí: Persistencia de Memoria de Skills Locales en Claude Code




