Módulo 2: Arquitectura Host-Client-Server

Descripción de la cápsula

En el módulo anterior entendiste qué es MCP, el problema M×N que resuelve, y usaste un MCP server existente en Claude Code. Viste que funciona — escribiste una petición, Claude Code usó un tool del MCP server, y recibiste una respuesta. Pero no viste cómo funciona internamente. Esa caja negra se abre en este módulo.

Vas a aprender la arquitectura de 3 capas que hace posible MCP: el Host (Claude Code), el Client (protocolo de comunicación), y el Server (tu código). Cada capa tiene responsabilidades distintas, y entender dónde empieza una y termina otra es la diferencia entre seguir recetas y realmente saber construir MCP servers.

Al terminar este módulo, podrás trazar un request completo — desde que escribes algo en Claude Code hasta que el MCP server responde — identificando qué pasa en cada capa, quién inicia qué, y dónde buscar cuando algo falla.

¿Dónde estamos?

Contexto en la guía

Esta es la Guía #5 de 11 del Claude Code Agentic Development Path. Estás en el Módulo 2 de Phase 1: Fundamentos MCP.

Phase 1: Fundamentos MCP (Módulos 1-3)
  ├── Módulo 1: Qué es MCP y Por Qué Importa ✅ Completado
  ├── Módulo 2: Arquitectura Host-Client-Server ← Estás aquí
  └── Módulo 3: Tres Primitivas — Resources, Tools, Prompts

Phase 2: Construir MCP Servers (Módulos 4-6)
  ├── Módulo 4: MCP Server en TypeScript
  ├── Módulo 5: MCP Server en Python
  └── Módulo 6: MCP Apps y UI Interactivo

Phase 3: Producción (Módulos 7-8)
  ├── Módulo 7: Testing, Debugging e Integración
  └── Módulo 8: Proyecto — MCP Server Real

Lo que ya sabes (Módulo 1)

Del módulo anterior traes estos conceptos sólidos:

✅ MCP es el "USB-C del AI" — un protocolo estándar para integraciones
✅ El problema M×N y cómo MCP lo reduce a M+N
✅ El ecosistema actual: hosts (Claude Code, Cursor, Windsurf), servers (filesystem, memory, GitHub)
✅ Configuraste y usaste un MCP server (Filesystem) en Claude Code

Lo que agregas en este módulo

Pasas de "sé qué es y sé que funciona" a "entiendo cómo funciona internamente":

Módulo 1: Qué es MCP
├── Problema M×N → Solución M+N
├── Ecosistema (hosts, servers)
└── Primer contacto práctico
    ↓
Módulo 2: Cómo funciona MCP (este módulo)
├── Arquitectura de 3 capas
├── Lifecycle de conexión
└── Flujo completo de request-response
    ↓
Módulo 3: Qué expone un MCP Server
├── Resources (datos)
├── Tools (funciones)
└── Prompts (templates)

La transición es directa: ya sabes que el MCP server respondió a tu petición. Ahora vas a ver exactamente cómo llegó esa petición al server y cómo volvió la respuesta.

La pregunta clave de este módulo

En el módulo 1, cuando le pediste a Claude Code "lista los archivos en mi directorio" y el Filesystem server respondió, pasaron estas cosas que no viste:

¿Qué pasó realmente?
│
├── ¿Quién decidió usar el Filesystem server y no otro?
├── ¿Cómo supo Claude Code qué tools tenía disponibles?
├── ¿En qué formato viajó tu petición al server?
├── ¿Cómo respondió el server?
├── ¿Qué pasa si el server falla?
├── ¿Y si hay 5 servers conectados simultáneamente?
└── ¿Quién maneja los permisos de cada operación?

Cada una de estas preguntas tiene una respuesta precisa en la arquitectura. Al terminar el módulo, todas serán obvias.

Objetivo del módulo

Al completar este módulo, serás capaz de:

✅ Dibujar la arquitectura Host-Client-Server de MCP sin ayuda
✅ Explicar el rol específico de cada capa en una oración
✅ Trazar un request completo: usuario escribe → Host procesa → Client envía → Server responde → respuesta llega al usuario
✅ Describir el lifecycle de conexión: initialize → discover capabilities → use → disconnect
✅ Explicar cómo un Host maneja múltiples Clients (Claude Code conectado a varios MCP servers simultáneamente)
✅ Identificar en qué capa buscar cuando algo falla

Roadmap del módulo

Cápsula	Tema	Qué aprenderás
02	El Host: el orquestador	Claude Code como Host — quién inicia la conexión, maneja permisos, decide qué tools usar
03	El Client: el conector	El protocolo de comunicación — lifecycle de conexión, capabilities negotiation, formato de mensajes
04	El Server: el proveedor	Tu código — exponer capabilities, responder requests, manejar estado
05	Flujo completo request-response	Trazar un request end-to-end + mini-proyecto: diagramar la arquitectura de tu setup

Flujo de aprendizaje

Primero entenderás la capa que ya conoces como usuario — el Host (Claude Code), la interfaz que usas directamente y quien orquesta todo (cápsula 02). Luego bajarás un nivel al Client, el componente invisible que maneja la comunicación entre Host y Server (cápsula 03). Después llegarás al Server, donde eventualmente escribirás tu código (cápsula 04). Finalmente, unirás las 3 capas en un flujo completo trazando un request de principio a fin (cápsula 05).

La progresión es de arriba hacia abajo: Host → Client → Server → Flujo completo. Empiezas con lo familiar (la interfaz que usas) y bajas hacia lo que construirás (el server).

Tiempo estimado

Cápsula	Contenido	Tiempo estimado
02	Host + conceptos + ejercicios	45-60 min
03	Client + protocolo + ejercicios	60-75 min
04	Server + patrones + ejercicios	60-75 min
05	Flujo completo + mini-proyecto	60-90 min
Total	Módulo completo	4-5 horas

Vista previa: las 3 capas en 30 segundos

Antes de profundizar en cada capa en las cápsulas siguientes, aquí tienes el mapa completo:

┌─────────────────────────────────────────────────┐
│                  MCP HOST                        │
│              (Claude Code)                       │
│                                                  │
│  "Soy la aplicación que el usuario ve.           │
│   Decido qué server usar para cada petición.     │
│   Manejo permisos y presento resultados."        │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │ MCP      │  │ MCP      │  │ MCP      │      │
│  │ Client 1 │  │ Client 2 │  │ Client 3 │      │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘      │
│       │              │              │            │
└───────┼──────────────┼──────────────┼────────────┘
        │              │              │
   JSON-RPC 2.0   JSON-RPC 2.0   JSON-RPC 2.0
   (via stdio)    (via stdio)    (via stdio)
        │              │              │
        ▼              ▼              ▼
   ┌─────────┐   ┌─────────┐   ┌─────────┐
   │ MCP     │   │ MCP     │   │ MCP     │
   │ Server  │   │ Server  │   │ Server  │
   │ (files) │   │ (GitHub)│   │ (DB)    │
   └─────────┘   └─────────┘   └─────────┘

   "Exponemos    "Exponemos    "Exponemos
    tools para    tools para    tools para
    archivos"     repos/PRs"    queries"

Cada capa tiene un trabajo claro:

Capa	Rol	En una oración
Host	Orquesta	Decide qué hacer, quién lo hace, y presenta el resultado
Client	Comunica	Traduce las decisiones del Host al protocolo MCP y las envía al Server
Server	Provee	Ejecuta la operación real y retorna el resultado

Esta tabla debería ser obvia al terminar el módulo. Si después de la cápsula 05 no puedes llenarla de memoria, vuelve y repasa.

Conexión con el proyecto

Mini-proyecto de este módulo

Vas a diagramar la arquitectura Host-Client-Server de tu setup actual de Claude Code. Tomarás los MCP servers que configuraste en el módulo anterior (al menos el Filesystem server) y trazarás el flujo completo de un request, identificando cada capa y su responsabilidad.

Conexión con el proyecto integrador (Módulo 8)

En el proyecto final construirás un MCP server production-ready. Entender la arquitectura ahora significa que cuando escribas tu server en los módulos 4-6:

Sabrás exactamente qué espera el Client de tu Server
Entenderás cómo el Host descubre las capabilities de tu Server
Podrás diagnosticar problemas sabiendo en qué capa buscar
Diseñarás tu Server sabiendo cómo encaja en la arquitectura completa

Sin este módulo, construirías servers siguiendo recetas. Con este módulo, construyes servers entendiendo el sistema.

Prerequisitos

Para este módulo necesitas:

✅ Haber completado el Módulo 1 (conceptos de MCP, primer contacto)
✅ Tener Claude Code instalado con al menos un MCP server configurado
✅ Comodidad leyendo diagramas de arquitectura y flujos de datos
✅ Familiaridad básica con conceptos de cliente-servidor (HTTP, APIs)

No necesitas: Conocimiento de protocolos específicos, experiencia con JSON-RPC, ni haber construido servers antes.

Límites: Qué NO se cubre en este módulo

❌ Implementación de código — No vas a escribir un MCP server todavía (eso viene en módulos 4-6)
❌ Las 3 primitivas en detalle — Resources, Tools, Prompts se cubren en módulo 3
❌ Transports en profundidad — stdio vs HTTP/SSE se cubren en módulos 4 y 5
❌ Especificación completa del protocolo — Este módulo cubre lo que necesitas saber como developer, no la spec técnica completa
❌ Testing y debugging — Se cubren en módulo 7

Este módulo es arquitectural y conceptual con ejemplos prácticos. Estás construyendo el mapa mental que guiará toda tu implementación futura.

Por qué la arquitectura importa

Podrías argumentar: "Ya sé que MCP funciona, ¿por qué necesito saber cómo funciona internamente?" Tres razones concretas:

1. Debugging efectivo

Cuando tu MCP server no responde, necesitas saber dónde buscar:

¿El Host no inicia la conexión?      → Problema de configuración
¿El Client no descubre capabilities? → Problema de inicialización
¿El Server no responde al request?   → Problema en tu código

Sin entender la arquitectura, cada error es un misterio. Con la arquitectura, cada error tiene una ubicación.

2. Diseño informado

Cuando diseñes tu MCP server, las decisiones dependen de entender las capas:

¿Qué capabilities exponer?   → Depende de qué el Host puede usar
¿Cómo manejar estado?        → Depende del lifecycle del Client
¿Qué errores retornar?       → Depende de qué el Client espera

3. Comunicación con tu equipo

Cuando expliques tu server a colegas o escribas documentación, necesitas el vocabulario correcto: "El Host descubre nuestras capabilities en la fase de inicialización" es mucho más preciso que "Claude Code se conecta y ve lo que puede hacer."

Un ejemplo rápido

Sin entender la arquitectura, este error es un misterio:

MCP Servers:
  filesystem: connected ✅
  github: disconnected ❌
  memory: connected ✅

Con la arquitectura, sabes exactamente dónde buscar:

github: disconnected

→ El Host lanzó el proceso del server (paso 1: ✅)
→ El Client intentó el handshake de inicialización (paso 2)
→ El Server no respondió correctamente (paso 2: ❌)
→ Causa probable: GITHUB_TOKEN no configurado
→ Solución: verificar variables de entorno del server

Los otros 2 servers no se ven afectados porque cada
Client-Server es una conexión independiente.

Eso es debugging con arquitectura. Pasaste de "no funciona" a "sé exactamente qué verificar."

Vocabulario clave del módulo

Estos son los términos que usarás en todo el módulo. No necesitas memorizarlos ahora — se irán anclando con cada cápsula:

Término	Significado	Primera vez que aparece
Host	Aplicación que el usuario usa (Claude Code)	Cápsula 02
Client	Componente dentro del Host que habla MCP con un Server	Cápsula 03
Server	Tu programa que expone capabilities	Cápsula 04
Capabilities	Lo que un Server puede hacer (tools, resources, prompts)	Cápsula 02
Initialize	Handshake entre Client y Server al conectarse	Cápsula 03
Lifecycle	Las fases de una conexión MCP (init → operate → close)	Cápsula 03
JSON-RPC	Formato de mensajes que usa MCP	Cápsula 03
Transport	Cómo viajan los mensajes (stdio, HTTP)	Cápsula 03
Handler	Función que procesa un request específico	Cápsula 04
inputSchema	Definición de parámetros de un tool (JSON Schema)	Cápsula 04

Evidencia de éxito

Al terminar este módulo, sabrás que tuviste éxito si:

✅ Puedes dibujar la arquitectura de 3 capas con flechas correctas de comunicación
✅ Puedes explicar en una oración qué hace cada capa: Host orquesta, Client comunica, Server provee
✅ Puedes trazar el camino de un request desde el usuario hasta el server y de vuelta
✅ Puedes explicar qué pasa cuando Claude Code se inicializa con un MCP server (el lifecycle)
✅ Puedes diagnosticar conceptualmente en qué capa está un problema dado un error
✅ Completaste el diagrama de tu setup actual de Claude Code

La analogía que usaremos en este módulo

En el módulo 1 usaste la analogía USB-C. En este módulo la analogía es un restaurante:

Restaurante MCP:

🧑‍💼 Host (Maître/Gerente) = Claude Code
   → Recibe al cliente (usuario)
   → Decide qué cocina puede satisfacer el pedido
   → Gestiona permisos (¿este cliente puede ordenar este plato?)
   → Coordina todo

📋 Client (Mesero) = Protocolo de comunicación
   → Toma el pedido del maître
   → Lo traduce al formato de la cocina
   → Lo lleva a la cocina correcta
   → Trae la respuesta de vuelta

👨‍🍳 Server (Cocina) = Tu código
   → Recibe el pedido del mesero
   → Lo prepara (ejecuta la operación)
   → Retorna el resultado

Un restaurante puede tener MÚLTIPLES cocinas:
├── Cocina italiana (MCP Server de GitHub)
├── Cocina japonesa (MCP Server de PostgreSQL)
└── Cocina mexicana (MCP Server de Filesystem)

El maître (Host) sabe qué puede servir cada cocina.
Cada cocina tiene su propio mesero (Client) dedicado.

Esta analogía te acompañará en las 4 cápsulas siguientes. Cada vez que algo no quede claro en la teoría, vuelve al restaurante.

La analogía mapeada a un request real

Veamos cómo se traduce al escenario concreto que ya experimentaste en el módulo 1:

Tú pides a Claude Code: "Lista los archivos en mi proyecto"

🧑‍💼 Maître (Host = Claude Code):
   "El cliente quiere saber qué archivos tiene.
    La cocina de filesystem (Filesystem Server) puede resolver esto.
    Le pido a su mesero que lleve el pedido."

📋 Mesero (Client):
   "Recibido. Traduzco el pedido al formato de la cocina:
    tools/call → list_directory → /Users/dev/project
    Lo envío por la ventanilla (stdin)."

👨‍🍳 Cocina (Server = Filesystem):
   "Pedido recibido. Ejecuto la operación: leo el directorio.
    Resultado: src/, package.json, README.md, test/
    Lo paso de vuelta por la ventanilla (stdout)."

📋 Mesero (Client):
   "La cocina respondió. Entrego el resultado al maître."

🧑‍💼 Maître (Host = Claude Code):
   "Recibido. Se lo presento al cliente de forma legible:
    'Tu proyecto tiene estos archivos: src/, package.json,
     README.md, test/'"

Eso que parece instantáneo cuando usas Claude Code — ese flujo completo sucede en milisegundos. Pero cada paso tiene un actor, un formato de datos, y un punto de posible falla.

Autoevaluación rápida antes de empezar

Antes de entrar a las cápsulas técnicas, verifica que tienes los prerequisitos del módulo 1. Responde mentalmente:

¿Puedes explicar qué es MCP en una oración? (Módulo 1, cápsula 03)
¿Puedes dar un ejemplo del problema M×N? (Módulo 1, cápsula 02)
¿Tienes al menos un MCP server configurado en Claude Code? (Módulo 1, cápsula 05)
¿Puedes ejecutar /mcp en Claude Code y ver un server "connected"? (Módulo 1, cápsula 05)

Si respondiste sí a las 4, estás listo. Si no, vuelve al módulo 1 antes de continuar. Este módulo construye directamente sobre esos conceptos.

Resumen

Este módulo cubre la arquitectura interna de MCP — las 3 capas que hacen que todo funcione
Progresión: Host (orquestador) → Client (conector) → Server (proveedor) → Flujo completo
Al terminar podrás trazar un request desde el usuario hasta el server y de vuelta
El mini-proyecto es diagramar tu setup actual de Claude Code
Todo lo que aprendes aquí te da las bases para construir MCP servers en módulos 4-6
Sin arquitectura, sigues recetas; con arquitectura, entiendes el sistema

Recursos adicionales

MCP Architecture Overview - Documentación oficial de la arquitectura
MCP Specification - Especificación técnica completa del protocolo
Introducing MCP (Anthropic Blog) - Contexto de diseño y decisiones arquitecturales
MCP TypeScript SDK - SDK que usarás en módulo 4 (útil para ver la arquitectura en código)
MCP Python SDK - SDK que usarás en módulo 5

Siguiente cápsula: El Host: el orquestador — cómo Claude Code actúa como Host MCP, quién inicia la conexión, cómo se manejan permisos, y por qué el Host es la pieza central de la arquitectura.

← AnteriorPrimer Contacto: Usar un MCP Server en Claude Code Siguiente →El Host: El Orquestador de MCP