Múltiples servidores: arquitectura con Claude Code

🔄 En la lección 5 construiste tu propio servidor MCP con FastMCP. Ahora vas a conectar múltiples servidores y orquestarlos desde Claude Code.

De un servidor a muchos

Un servidor solo ya es útil. Pero la magia real aparece cuando conectas varios y dejas que la IA los combine automáticamente.

Imagina este escenario: “Revisa los issues abiertos del repo, consulta los logs de errores en la base de datos, genera un reporte y publícalo en Slack.” Eso requiere GitHub MCP + PostgreSQL MCP + Slack MCP trabajando juntos. Y con Claude Code, no necesitas escribir ni una línea de integración.

Agregar servidores a Claude Code

Claude Code usa el comando claude mcp add para registrar servidores:

# Agregar GitHub MCP
claude mcp add github -e GITHUB_TOKEN=ghp_tu_token -- npx -y @modelcontextprotocol/server-github

# Agregar PostgreSQL MCP
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://reader:pass@localhost/midb

# Agregar Brave Search
claude mcp add brave-search -e BRAVE_API_KEY=tu_clave -- npx -y @modelcontextprotocol/server-brave-search

La flag -e pasa variables de entorno al servidor. El nombre que elijas (github, postgres, brave-search) es el identificador dentro de Claude Code.

Scope: proyecto vs usuario

# Solo para este repositorio — se guarda en .mcp.json
claude mcp add github --scope project -- npx -y @modelcontextprotocol/server-github

# Para todos tus proyectos — config personal
claude mcp add github --scope user -- npx -y @modelcontextprotocol/server-github

Consejo: Con --scope project, tu equipo puede clonar el repo y tener los mismos servidores MCP configurados automáticamente.

✅ Quick Check: Si quieres que todo tu equipo use el mismo servidor PostgreSQL MCP, ¿qué scope usas? (–scope project, para que la config se guarde en .mcp.json dentro del repositorio.)

Tool Search: la optimización clave

Cuando conectas 5-10 servidores, cada uno con 10-20 herramientas, el total de definiciones enviadas al modelo crece rápido. Más tokens = más lento y más caro.

Tool Search resuelve esto: en vez de enviar las 100+ definiciones al modelo, solo envía las que son relevantes para la tarea actual.

Anthropic reporta un 46.9% de ahorro de tokens con Tool Search activado.

Sin Tool Search:
→ 100 herramientas × ~200 tokens cada una = 20,000 tokens de contexto

Con Tool Search:
→ Solo 5-10 herramientas relevantes = ~2,000 tokens
→ El modelo trabaja más rápido, responde mejor

Tool Search se activa automáticamente en Claude Code cuando tienes múltiples servidores. No necesitas configurar nada.

El loop agéntico en la práctica

Recuerda el patrón de la lección 4: contexto → acción → verificación → repetir. Así funciona con múltiples servidores:

Tú: "Revisa el PR #42 y si tiene bugs, crea issues para cada uno"

Claude Code (automáticamente):
1. GitHub MCP → Lee el diff del PR #42
2. Filesystem MCP → Lee los archivos modificados con contexto completo
3. Análisis → Identifica 3 posibles bugs
4. GitHub MCP → Crea issue #101: "Null check missing in auth.py"
5. GitHub MCP → Crea issue #102: "SQL injection risk in query.py"
6. GitHub MCP → Crea issue #103: "Race condition in cache.py"
7. Verificación → Confirma que los 3 issues fueron creados

Siete pasos, tres servidores, cero código de integración. La IA decide qué herramienta usar en cada paso.

Combinaciones prácticas

Estos son flujos que funcionan con los servidores de la lección 3:

Code review automatizado (GitHub + Filesystem):

"Analiza los últimos 5 PRs mergeados. ¿Hay patrones de bugs recurrentes?"

Consulta de datos + exportación (PostgreSQL + Filesystem):

"Consulta las ventas del último mes y genera un CSV con los totales por región"

Investigación + comunicación (Brave Search + Slack):

"Busca las últimas vulnerabilidades de Node.js y publica un resumen en #seguridad"

Flujo completo de desarrollo (GitHub + PostgreSQL + Filesystem + Slack):

"Revisa los issues con label 'bug', consulta los logs de error relacionados,
propón un fix para el más crítico y notifica al equipo en #dev"

✅ Quick Check: ¿Por qué Tool Search es importante cuando tienes 10+ servidores conectados? (Porque sin él, enviarías las definiciones de 100+ herramientas al modelo en cada mensaje — gastando tokens innecesariamente y reduciendo la calidad de las respuestas.)

Exponer tu servidor con claude mcp serve

¿Recuerdas el servidor de tareas de la lección 5? Puedes exponerlo directamente en Claude Code:

# Registrar tu servidor personalizado
claude mcp add mi-todo -- python /ruta/a/todo_server.py

# Verificar que está conectado
claude mcp list

Una vez registrado, Claude Code puede usar tus herramientas personalizadas junto con GitHub, PostgreSQL y cualquier otro servidor. Tu servidor participa en el mismo loop agéntico.

Puntos clave

• claude mcp add registra servidores — usa -e para variables de entorno
• --scope project para el equipo (.mcp.json), --scope user para uso personal
• Tool Search ahorra ~47% de tokens seleccionando solo las herramientas relevantes
• El loop agéntico combina múltiples servidores automáticamente: contexto → acción → verificación
• Servidores personalizados (FastMCP) se integran igual que los oficiales

Siguiente lección

Ya sabes combinar servidores y orquestarlos con Claude Code. Pero ¿qué pasa si algo sale mal? En la lección 7 veremos seguridad MCP — las 5 amenazas más comunes y cómo proteger tu entorno.