MCP Servers en Claude Code

La flota de droides de la Alianza Rebelde • D3 Claude Code • 20% del examen CCA-F

La flota de droides: cada MCP server, un especialista

La Alianza Rebelde no tiene un solo droid que hace todo. R2-D2 navega y hackea sistemas imperiales. C-3PO traduce y negocia protocolos diplomáticos. BB-8 hace reconocimiento de terreno. R4-P17 maneja los archivos técnicos de las naves. Cada uno especializado. Cada uno con capacidades únicas. Y todos disponibles para la misión cuando el Consejo Jedi los necesita.

Eso es exactamente lo que hacen los MCP servers en Claude Code. Sin ellos, Claude Code puede leer archivos, ejecutar shell y abrir URLs — potente, pero limitado a lo local. Con MCP servers configurados, puede consultar tu base de datos PostgreSQL, crear pull requests en GitHub, enviar mensajes a Slack, buscar en tu wiki interna, y cualquier otra cosa que un servidor exponga.

Cada MCP server es un droid que vos incorporás a la flota. Y Claude Code — como el Consejo Jedi — decide cuándo llamar a cuál, según lo que la misión necesite. En este video aprendés a conectar esos droides: cómo configurarlos, cómo verificar que funcionan, cómo manejar sus credenciales de forma segura, y cómo Claude Code toma esa decisión de cuál usar.

Esta es la flota del proyecto rebel_api:

Los 2 transportes: cable directo vs. holocomm

Antes de configurar cualquier MCP server, hay una decisión de diseño: ¿cómo se conecta Claude Code a él? Los dos transportes disponibles son stdio y HTTP/SSE, y la elección cambia la arquitectura completa del deployment:

La configuración en settings.json es diferente para cada uno:

settings.json — stdio vs HTTP/SSE

CRÍTICO: NUNCA escribas tokens, passwords ni API keys directamente en settings.json. El archivo puede commitarse por error y exponer credenciales al repositorio. El patrón correcto es variables de entorno: ${VAR_NAME}. Claude Code expande esa variable desde el entorno del proceso al momento de conectarse. R2-D2 no lleva los códigos de acceso escritos en su carcasa — los recupera del sistema de autenticación seguro cuando los necesita.

🎯 TRAMPA DE EXAMEN: El examen puede mostrarte un settings.json con una API key hardcodeada y preguntarte qué problema tiene. La respuesta: riesgo de exposición de credenciales si se commitea el archivo. La solución: variables de entorno con la sintaxis ${VAR_NAME}.

Los 3 scopes: ¿qué droid va en qué nave?

No todos los MCP servers deben estar disponibles en todos los proyectos. El scope determina en qué contextos Claude Code puede ver cada servidor:

La regla práctica es simple: si el MCP server tiene sentido solo en un proyecto (la DB de ese proyecto, la API de ese servicio), scope proyecto. Si lo usás en cualquier proyecto (GitHub, Slack, herramientas personales), scope usuario. Si el admin lo impone para toda la organización, scope empresa.

Scope proyecto (.claude/settings.json) se puede commitear al repositorio — todo el equipo lo tiene disponible automáticamente al clonar. Las credenciales siempre van por variables de entorno, nunca en el archivo committed. El mismo settings.json puede tener la configuración sin los secretos.

🎯 TRAMPA DE EXAMEN: El examen distingue entre scope proyecto y scope usuario. Si la pregunta dice 'disponible para todos los proyectos del usuario', la respuesta es ~/.claude/settings.json. Si dice 'específico de este repo', es .claude/settings.json.

/mcp: llamada a lista de la flota

Una vez configurados los MCP servers, el slash command /mcp dentro de una sesión interactiva es tu panel de control de la flota. Te dice qué droides están conectados y cuáles tienen problemas:

Sesión interactiva — /mcp en acción

/mcp te da tres estados posibles para cada servidor: conectado (✅), error al iniciar (❌), y sin respuesta al handshake MCP (⚠️). Para diagnóstico más profundo existe /doctor — muestra la configuración completa, versiones, y problemas detectados en el entorno.

Diferencia importante para el examen: ❌ error significa que el proceso no pudo iniciarse en absoluto — típicamente falta una dependencia o hay un error de ruta. ⚠️ sin respuesta significa que el proceso sí se inició pero no respondió al handshake MCP — puede ser un error silencioso en el startup del servidor o un problema de configuración.

¿Cómo decide Claude Code cuándo usar un MCP tool?

Al inicio de cada sesión, Claude Code recibe la lista completa de tools disponibles: las built-ins (Read, Write, Bash, Browser) y todas las expuestas por los MCP servers conectados. El modelo razona sobre cuál es más apropiada para cada tarea basándose en tres cosas: el nombre y descripción de cada tool, el contexto de la tarea actual, y las instrucciones del CLAUDE.md.

Esto conecta directamente con M2V1 (Tool Design): las descripciones de tus MCP tools son decisivas para que Claude Code las use correctamente. Si query_database dice 'Ejecuta una query SQL de solo lectura. NO usar para INSERT/UPDATE/DELETE', el modelo va a respetar eso. Si la descripción es vaga, el modelo puede elegir mal o no elegir la tool cuando debería. La calidad de las descripciones determina la calidad del razonamiento.

También podés agregar una sección de MCPs en tu CLAUDE.md del proyecto explicando cuándo usar cada servidor. Eso refuerza las instrucciones y reduce ambigüedad en tareas complejas donde múltiples herramientas podrían ser válidas.

Demo: rebel-db + rebel-github trabajando juntos

El servidor rebel-db completo — R2-D2 con acceso a SQLite:

.claude/mcp/db_server.py — rebel-db MCP server (stdio)

El settings.json completo con permisos granulares por MCP tool:

.claude/settings.json — flota completa con least privilege

Least privilege en acción (principio de M2V4): Claude Code puede leer la DB libremente, pero no puede escribir sin aprobación explícita. Puede crear un PR, pero no puede mergearlo — eso requiere revisión humana. El formato de permiso granular es mcp__<nombre-servidor>__<nombre-tool>. Con wildcard: mcp__rebel-db__* permite todas las tools de ese servidor.

Y así se ve la flota coordinada trabajando en una tarea real:

Terminal — Claude Code coordinando droides

Observá el razonamiento del agente: usó list_tables primero para conocer el esquema, query_database para el conteo, list_issues del MCP de GitHub para verificar. Cuando detectó que create_issue no estaba en los permisos, lo reportó claramente en lugar de fallar silenciosamente. Los droides trabajan en equipo — y saben cuándo uno no tiene autorización para actuar.

Trampas de examen: lo que pregunta el CCA-F

🎯 TRAMPA DE EXAMEN: '¿Cuándo usar stdio vs HTTP/SSE?' stdio = servidor en la misma máquina, Claude Code lo lanza como proceso hijo. HTTP/SSE = servidor ya corriendo, puede ser remoto. No es una preferencia — es una decisión de arquitectura basada en dónde corre el servidor.

🎯 TRAMPA DE EXAMEN: 'Configurás un MCP server con la API key directamente en settings.json. ¿Qué problema tiene?' El archivo puede commitarse accidentalmente al repositorio, exponiendo las credenciales. Solución: ${VAR_NAME} para variables de entorno.

🎯 TRAMPA DE EXAMEN: '¿Qué scope usás para un MCP server disponible en todos los proyectos del usuario?' ~/.claude/settings.json — scope usuario. Si dijiste .claude/settings.json, eso es scope proyecto (solo aplica a ese repo).

🎯 TRAMPA DE EXAMEN: '¿Cómo Claude Code decide usar un MCP tool en lugar de Read para leer datos?' Razona sobre el nombre y descripción de las tools disponibles. Si la descripción del MCP tool explica cuándo usarlo (y el contexto encaja), lo elige. Las descripciones vagas llevan a elecciones malas.

🎯 TRAMPA DE EXAMEN: 'Claude Code puede leer la DB pero no escribir. ¿Cómo configurás eso?' En permissions.allow: mcp__rebel-db__query_database y mcp__rebel-db__list_tables. En permissions.deny: mcp__rebel-db__execute_transaction. O allow mcp__rebel-db__* + deny execute_transaction específicamente (deny gana).

🎯 TRAMPA DE EXAMEN: '¿Qué significa ⚠️ en el output de /mcp?' El servidor inició pero no respondió al handshake MCP — puede ser un error silencioso en el startup. No confundir con ❌ que significa que el proceso no pudo iniciarse en absoluto.

May the MCP be with you

La Alianza Rebelde ganó la batalla de Endor porque cada droid hizo lo suyo. R2-D2 desbloqueó la puerta. C-3PO distrajo a los Ewoks. BB-8 mantuvo los escudos. Ninguno intentó hacer el trabajo de los demás.

Tu flota de MCP servers funciona igual: cada uno especializado, todos coordinados por Claude Code, con permisos claros sobre qué puede hacer cada uno. El principio de menor privilegio no es un obstáculo — es lo que hace que el sistema sea seguro a medida que escala.

Resumen para el examen: 2 transportes (stdio = local + proceso hijo, HTTP/SSE = remoto + ya corriendo). 3 scopes (proyecto, usuario, empresa). Secretos siempre como variables de entorno ${VAR}. /mcp para ver estado de la flota (✅ ❌ ⚠️). Permisos granulares con mcp__servidor__tool. Claude Code elige tools basándose en sus descripciones — igual que en M2V1.

En M3V4 vemos workflows de CI/CD con Claude Code: cómo integrarlo en GitHub Actions, cómo usar el modo no-interactivo para automatizar tareas de revisión y testing, y cómo construir pipelines donde el agente es un paso más del flujo de desarrollo.