Primer Contacto: Usar un MCP Server en Claude Code

Descripción de la cápsula

Has entendido el problema M×N, la solución MCP, y el ecosistema actual. Ahora es momento de ver MCP en acción. En esta cápsula vas a configurar un MCP Server existente en Claude Code y usarlo para resolver tareas reales. No vas a construir un server todavía (eso viene en módulos 3-6) — vas a ser el usuario de uno.

Este primer contacto es crucial. Ver un MCP Server funcionando — donde Claude Code usa herramientas externas como si fueran nativas — ancla todo lo conceptual en algo tangible. Cuando el server responda a tu request, el modelo mental de MCP dejará de ser abstracto.

Preparación: lo que necesitas

Antes de empezar, verifica que tienes todo listo:

# 1. Claude Code instalado y actualizado
claude --version
# Debe mostrar versión reciente

# 2. Node.js instalado (necesario para servers en TypeScript)
node --version
# Debe ser v18+ 

# 3. npm disponible
npm --version

# 4. npx disponible (viene con npm)
npx --version

Verificación: Si los 4 comandos retornan versiones, estás listo. Si alguno falla, instálalo antes de continuar.

Si falta algo:

# Instalar Node.js (si no lo tienes)
# macOS con Homebrew:
brew install node

# Verificar que todo quedó instalado
node --version && npm --version && npx --version

Preparar un directorio de prueba

Para que los ejemplos funcionen, necesitas un directorio con archivos. Puedes usar uno existente o crear uno de prueba:

# Crear directorio de prueba con contenido
mkdir -p ~/mcp-playground/src
mkdir -p ~/mcp-playground/docs

echo "# Mi Proyecto MCP" > ~/mcp-playground/README.md
echo '{"name": "mcp-playground", "version": "1.0.0", "dependencies": {"express": "^4.18.0", "typescript": "^5.0.0"}}' > ~/mcp-playground/package.json
echo "console.log('Hello MCP')" > ~/mcp-playground/src/index.js
echo "// TODO: implement user authentication" > ~/mcp-playground/src/auth.js
echo "// TODO: add error handling" > ~/mcp-playground/src/utils.js
echo "# Notas del proyecto" > ~/mcp-playground/docs/notes.md
echo "def main(): pass  # TODO: implement" > ~/mcp-playground/src/app.py

Verifica que se creó correctamente:

ls -la ~/mcp-playground/
# Deberías ver: README.md, package.json, src/, docs/

ls -la ~/mcp-playground/src/
# Deberías ver: index.js, auth.js, utils.js, app.py

MCP Server que vamos a usar: Filesystem

Vamos a configurar el Filesystem MCP Server oficial. Es ideal como primer contacto porque:

• ✅ Es un server oficial de Anthropic (confiable, bien documentado)
• ✅ No requiere API keys ni cuentas externas
• ✅ Trabaja con tu sistema de archivos local (resultados inmediatos)
• ✅ Expone tools claros y fáciles de entender
• ✅ Puedes verificar los resultados mirando tus archivos directamente

Qué puede hacer el Filesystem Server

Tools disponibles:
├── read_file          → Lee el contenido de un archivo
├── read_multiple_files → Lee varios archivos a la vez
├── write_file         → Escribe contenido a un archivo
├── edit_file          → Edita un archivo existente
├── create_directory   → Crea una carpeta
├── list_directory     → Lista archivos y carpetas
├── directory_tree     → Muestra estructura en árbol
├── move_file          → Mueve o renombra un archivo
├── search_files       → Busca archivos por patrón
├── get_file_info      → Metadata de un archivo
└── list_allowed_directories → Muestra directorios permitidos

Paso 1: Configurar el MCP Server en Claude Code

Opción A: Configuración vía comando (recomendada)

Claude Code permite agregar MCP servers desde la terminal:

# Agregar el Filesystem MCP Server
# Reemplaza /Users/tu-usuario/mcp-playground con tu directorio real
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem /Users/tu-usuario/mcp-playground

Desglose del comando:

claude mcp add          # Comando para agregar un MCP server
  filesystem            # Nombre que le das al server (puedes elegir cualquiera)
  -s user               # Scope: "user" (disponible en todas tus sesiones)
  --                    # Separador entre args de claude y args del server
  npx -y                # Ejecuta el package sin instalarlo globalmente
  @modelcontextprotocol/server-filesystem  # Package del server oficial
  /Users/tu-usuario/mcp-playground         # Directorio al que tendrá acceso

Verificación inmediata del paso 1

Verifica que el server se registró correctamente:

# Listar MCP servers configurados
claude mcp list

Deberías ver algo como:

User-scoped MCP servers:
  filesystem: npx -y @modelcontextprotocol/server-filesystem /Users/tu-usuario/mcp-playground

Si ves tu server listado, la configuración fue exitosa.

Opción B: Configuración manual vía JSON

Si prefieres configurar manualmente, edita el archivo de configuración:

# Abrir el archivo de configuración de Claude Code
# La ubicación depende de tu sistema:

# macOS/Linux:
cat ~/.claude/settings.json

Agrega la configuración del MCP server:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/tu-usuario/mcp-playground"
      ]
    }
  }
}

Paso 2: Verificar que el server está conectado

Abre una nueva sesión de Claude Code:

# Iniciar Claude Code
claude

Verifica que el MCP server se cargó correctamente:

# Dentro de Claude Code, usa el comando /mcp
/mcp

Deberías ver algo como:

MCP Servers:
  filesystem: connected
    Tools:
      - read_file
      - write_file
      - list_directory
      - search_files
      - ...

Checklist de verificación

• ✅ El server aparece con status connected
• ✅ Se listan los tools disponibles
• ✅ El nombre coincide con el que configuraste (filesystem)

Si ves connected, tu MCP server está funcionando. Si no, ve a la sección de Troubleshooting al final.

Paso 3: Usar el MCP Server

Ahora viene la parte interesante. Con el server conectado, puedes pedirle a Claude Code que use sus herramientas. Claude Code decidirá automáticamente cuándo usar los tools del MCP Server.

Ejemplo 1: Explorar un directorio

Tú: "¿Qué archivos hay en mi directorio de proyectos?"

Claude Code va a:

1. Identificar que tiene el tool list_directory disponible
2. Invocar el tool con el path de tu directorio
3. Recibir la lista de archivos del MCP Server
4. Presentarte los resultados

Output esperado:

Aquí están los archivos en /Users/tu-usuario/mcp-playground:

📁 src/
📁 docs/
📄 README.md
📄 package.json

Verifica: Abre tu terminal por separado y ejecuta ls ~/mcp-playground. ¿Coincide con lo que Claude Code mostró? Debería ser idéntico.

Ejemplo 2: Leer un archivo

Tú: "Lee el archivo package.json y dime qué dependencias tengo"

Claude Code va a:

1. Usar read_file con el path al archivo
2. Recibir el contenido del archivo
3. Procesar y analizar el contenido

Verifica: Abre ~/mcp-playground/package.json en tu editor. ¿El contenido que Claude Code leyó es correcto?

Ejemplo 3: Buscar archivos

Tú: "Busca todos los archivos .js en mis proyectos"

Claude Code va a:

1. Usar search_files con el patrón *.js
2. Recibir la lista de archivos JavaScript
3. Presentarte los resultados organizados

Verifica: Ejecuta find ~/mcp-playground -name "*.js" en tu terminal. ¿Los resultados coinciden?

Ejemplo 4: Crear un archivo

Tú: "Crea un archivo llamado ideas.md con una lista de 5 ideas para proyectos MCP"

Claude Code va a:

1. Generar el contenido basado en tu pedido
2. Usar write_file para crear el archivo
3. Confirmar que el archivo fue creado

Nota: Claude Code te pedirá confirmación antes de escribir archivos, por seguridad.

Verifica: Después de que Claude Code confirme la creación, ejecuta cat ~/mcp-playground/ideas.md en tu terminal. ¿El archivo existe y tiene el contenido correcto?

Ejemplo 5: Estructura de directorio

Tú: "Muéstrame la estructura completa del directorio"

Claude Code va a:

1. Usar directory_tree en el directorio configurado
2. Presentar la estructura en formato árbol

Verifica: Ejecuta tree ~/mcp-playground (si tienes tree instalado) o find ~/mcp-playground -type f para comparar.

Paso 4: Observar el flujo MCP

Mientras usas el server, presta atención a lo que pasa. Cuando Claude Code decide usar un tool del MCP Server, verás algo como:

⏳ Using MCP tool: filesystem.read_file
   Path: /Users/tu-usuario/mcp-playground/README.md

Esto te muestra:

• Qué tool se usa — read_file del server filesystem
• Con qué argumentos — el path al archivo
• Que es automático — Claude Code decide cuándo usar el tool basado en tu petición

Esto es MCP en acción. El Host (Claude Code) usa el Client (interno) para invocar un Tool en el Server (filesystem), recibe la respuesta, y la presenta al usuario. Exactamente el flujo que viste en la cápsula anterior.

Qué observar mientras usas MCP

Mientras experimentas, presta atención a estos aspectos del flujo del protocolo — entender estos detalles te ayudará cuando construyas tus propios servers:

1. Discovery automático

Cuando Claude Code arranca, contacta cada MCP server configurado y le pregunta "¿qué puedes hacer?" El server responde con su lista de capabilities. Observa: cuando corres /mcp, la lista de tools que ves es el resultado de ese proceso de discovery. Claude Code no tiene esa información hardcoded — la obtiene del server en tiempo real.

2. Selección inteligente de tools

Claude Code no usa MCP tools aleatoriamente. Observa qué peticiones activan tools y cuáles no:

"¿Qué es MCP?"                    → NO usa MCP tools (puede responder sin ellos)
"Lee mi archivo README.md"        → SÍ usa read_file
"¿Cuántos archivos .py tengo?"    → SÍ usa search_files o list_directory
"Explícame qué es TypeScript"     → NO usa MCP tools

3. Confirmación de operaciones de escritura

Observa que Claude Code pide confirmación antes de operaciones que modifican archivos (write_file, edit_file, move_file), pero no para operaciones de lectura (read_file, list_directory). Esta es una medida de seguridad del Host, no del protocolo.

4. Formato de respuestas

Observa cómo Claude Code transforma las respuestas crudas del server en lenguaje natural. El server retorna JSON (ej: {"files": ["a.js", "b.py"]}), pero tú ves una respuesta humana. Esa transformación la hace el Host, no el server.

5. Latencia

Observa que la primera vez que usas un tool puede tomar un par de segundos (porque npx necesita descargar el package). Las llamadas posteriores son más rápidas. En la sección de troubleshooting verás cómo resolver esto si te molesta.

Paso 5 (Opcional): Configurar un segundo MCP Server

Para experimentar con múltiples servers simultáneos, puedes agregar otro. El Memory Server es una buena opción:

# Agregar Memory MCP Server
claude mcp add memory -s user -- npx -y @modelcontextprotocol/server-memory

Verificar ambos servers

# Listar servers configurados
claude mcp list
# Deberías ver: filesystem y memory

# En Claude Code, verificar conexiones
/mcp
# Deberías ver ambos como "connected"

Ahora Claude Code tiene acceso a dos MCP servers:

• filesystem — para operaciones con archivos
• memory — para almacenar y recuperar información persistente

Prueba:

Tú: "Recuerda que mi lenguaje favorito es Python y que estoy 
     aprendiendo MCP"
→ Claude Code usa memory.store_memory()

Tú: "¿Cuál es mi lenguaje favorito?"
→ Claude Code usa memory.retrieve_memory()
→ Responde: "Tu lenguaje favorito es Python"

Esto demuestra el principio composable — múltiples MCP servers funcionando juntos, cada uno con sus capabilities específicas. Claude Code elige qué server usar basado en tu petición.

Combinando ambos servers

Prueba una petición que use ambos servers:

Tú: "Lee mi archivo README.md y recuérdalo para futuras sesiones"
→ Claude Code usa filesystem.read_file() para leer el contenido
→ Luego usa memory.store_memory() para guardarlo
→ "Leí tu README.md y lo guardé en memoria."

Ejercicios

Ejercicio 1: Configurar un tercer MCP Server (Fácil)

Configura el Fetch MCP Server (para hacer HTTP requests) y verifica que funciona:

claude mcp add fetch -s user -- npx -y @modelcontextprotocol/server-fetch

Ejercicio 2: Buscar TODOs en tu código (Medio)

Usando el Filesystem MCP Server, pídele a Claude Code que busque todos los comentarios TODO en los archivos de tu directorio de prueba.

"Busca todos los archivos en mi directorio y muéstrame los que contengan 
la palabra 'TODO'. Para cada uno, muéstrame la línea con el TODO."

Encontré TODOs en los siguientes archivos:

📄 src/auth.js (línea 1):
   // TODO: implement user authentication

📄 src/utils.js (línea 1):
   // TODO: add error handling

📄 src/app.py (línea 1):
   def main(): pass  # TODO: implement

Ejercicio 3: Crear una estructura de directorio (Medio)

Pídele a Claude Code que cree una estructura de directorio para un nuevo proyecto dentro de tu playground:

Crea dentro de mi directorio una carpeta llamada "new-project" 
con la siguiente estructura:
- src/
  - index.ts
  - config.ts
- tests/
  - index.test.ts
- README.md con el título "Nuevo Proyecto MCP"

# Verifica que la estructura se creó
tree ~/mcp-playground/new-project/
# O si no tienes tree:
find ~/mcp-playground/new-project/ -type f

new-project/
├── README.md
├── src/
│   ├── index.ts
│   └── config.ts
└── tests/
    └── index.test.ts

Ejercicio 4: Usar múltiples servers en un flujo (Difícil)

Si configuraste el Filesystem y Memory servers, prueba un flujo que use ambos:

1. Pídele a Claude Code que lea tu package.json
2. Que extraiga las dependencias
3. Que recuerde esa información para futuras sesiones

"Lee mi package.json, extrae las dependencias, y recuérdalas 
para futuras sesiones. Luego confirma qué guardaste."

"¿Qué dependencias tiene mi proyecto?"
→ Claude Code usa memory.retrieve_memory()
→ "Tu proyecto tiene express ^4.18.0 y typescript ^5.0.0"

Mini-proyecto del módulo: Mapear integraciones M×N vs M+N

Ahora que has experimentado con MCP, completa el mini-proyecto de este módulo.

Objetivo

Mapear 3 integraciones reales de tu día a día al modelo M×N vs M+N.

Instrucciones

1. Lista 3 integraciones que usas o desearías tener:

   • Ejemplo: "Quiero que Claude Code acceda a mi PostgreSQL database"
   • Ejemplo: "Quiero que Cursor pueda buscar en mi Notion"
   • Ejemplo: "Quiero que mi AI coding assistant consulte la documentación interna"

2. Para cada una, dibuja:

   • Modelo M×N: ¿Cuántas integraciones custom necesitarías si quieres que funcione en 3 AI hosts diferentes?
   • Modelo M+N: ¿Cuántas implementaciones necesitarías con MCP?

3. Calcula el ahorro:

   • Total M×N vs Total M+N
   • Porcentaje de reducción

4. Reflexiona:

   • ¿Alguna de estas integraciones ya existe como MCP Server?
   • ¿Cuál sería la más valiosa para construir como proyecto final de esta guía?

Formato de entrega

# Mini-Proyecto Módulo 1: Integraciones M×N vs M+N

## Mis 3 integraciones deseadas

### 1. [Nombre de la integración]
- **Servicio:** [Qué servicio]
- **AI Hosts donde la quiero:** [Lista de hosts]
- **M×N:** [Cálculo]
- **M+N:** [Cálculo]
- **¿Existe MCP Server?:** [Sí/No/Parcial]

### 2. [Nombre de la integración]
[...]

### 3. [Nombre de la integración]
[...]

## Totales
- **Total M×N:** [Suma]
- **Total M+N:** [Suma]
- **Ahorro:** [Porcentaje]

## Reflexión
- **Integración más valiosa para mi proyecto final:** [Cuál y por qué]

# Mini-Proyecto Módulo 1: Integraciones M×N vs M+N

## Mis 3 integraciones deseadas

### 1. PostgreSQL Database
- **Servicio:** PostgreSQL (database del proyecto actual)
- **AI Hosts:** Claude Code, Cursor, Windsurf
- **M×N:** 3 hosts × 1 servicio = 3 integraciones custom
- **M+N:** 3 clients + 1 server = 4 implementaciones (pero los clients ya existen)
- **¿Existe MCP Server?:** ✅ Sí, server oficial de Anthropic

### 2. Notion Knowledge Base
- **Servicio:** Notion (documentación del equipo)
- **AI Hosts:** Claude Code, Cursor, Windsurf
- **M×N:** 3 × 1 = 3 integraciones custom
- **M+N:** 3 + 1 = 4 (clients ya existen, solo necesito el server)
- **¿Existe MCP Server?:** ✅ Sí, community server

### 3. Internal API (microservicios internos)
- **Servicio:** API interna del trabajo (no pública)
- **AI Hosts:** Claude Code, Cursor
- **M×N:** 2 × 1 = 2 integraciones custom
- **M+N:** 2 + 1 = 3 (solo necesito construir el server)
- **¿Existe MCP Server?:** ❌ No, tendría que construirlo yo

## Totales
- **Total M×N:** 3 + 3 + 2 = 8 integraciones custom
- **Total M+N:** En realidad, solo necesito construir 1-3 MCP servers
  (los clients ya existen en los hosts)
- **Ahorro:** >60% de esfuerzo de desarrollo

## Reflexión
- **Integración más valiosa:** La Internal API, porque es la única
  que no tiene MCP Server existente y sería la más impactante para
  mi equipo. Podría ser mi proyecto final del módulo 8.

Troubleshooting

"Claude Code no usa los tools del MCP Server"

Causa: Claude Code decide cuándo usar tools basado en tu petición. Si tu pregunta no requiere acceso a archivos, no usará el Filesystem server.

Solución: Haz peticiones específicas que requieran acceso a archivos:

• ✅ "Lee el archivo package.json de mi proyecto"
• ✅ "Lista los archivos en mi directorio"
• ❌ "¿Qué es MCP?" (esto no requiere filesystem)

"Error: ENOENT — no such file or directory"

Causa: El directorio que configuraste no existe o el path tiene un typo.

Solución:

# Verificar que el directorio existe
ls -la /tu/directorio/configurado

# Si necesitas cambiar el directorio:
claude mcp remove filesystem
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem /directorio/correcto

"Error: permission denied"

Causa: El MCP Server no tiene permisos para acceder al directorio.

Solución:

# Verificar permisos
ls -la /tu/directorio

# Ajustar si es necesario
chmod 755 /tu/directorio

"npx tarda mucho en arrancar"

Causa: npx descarga el package cada vez que se ejecuta si no está cacheado.

Solución:

# Instalar globalmente para arranque más rápido
npm install -g @modelcontextprotocol/server-filesystem

# Reconfigurar usando el path global
claude mcp remove filesystem
claude mcp add filesystem -s user -- server-filesystem /tu/directorio

"El server aparece como disconnected"

Causa: El server no pudo arrancar. Puede ser un problema de Node.js, del package, o de configuración.

Solución:

# 1. Verificar que npx puede ejecutar el server manualmente
npx -y @modelcontextprotocol/server-filesystem --help

# 2. Si falla, puede ser un problema de versión de Node.js
node --version
# Necesitas v18+

# 3. Limpiar cache de npm y reintentar
npm cache clean --force
claude mcp remove filesystem
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem /tu/directorio

# 4. Reiniciar Claude Code (nueva sesión)
claude

"Los tools no aparecen en /mcp"

Causa: El server se registró pero no se conectó correctamente al iniciar la sesión.

Solución:

# 1. Verificar la configuración
claude mcp list

# 2. Si aparece listado pero no connected, intentar:
# - Cerrar Claude Code completamente
# - Volver a abrir con: claude

# 3. Si persiste, remover y re-agregar:
claude mcp remove filesystem
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem /tu/directorio

# 4. Si nada funciona, verificar que no hay conflictos en settings.json
cat ~/.claude/settings.json

Resumen

En esta cápsula:

• Preparaste tu entorno: Node.js, npm, npx, y un directorio de prueba
• Configuraste tu primer MCP Server (Filesystem) en Claude Code
• Verificaste la conexión con el comando /mcp y confirmaste que los tools están disponibles
• Usaste el server para leer archivos, listar directorios, buscar archivos, y crear archivos
• Observaste el flujo MCP en acción: Host → Client → Server → Respuesta
• Notaste patrones clave: discovery automático, selección inteligente de tools, confirmación de escritura
• Experimentaste (opcionalmente) con múltiples servers simultáneos (Filesystem + Memory)
• Completaste ejercicios de práctica con MCP tools reales
• Completaste el mini-proyecto: mapear integraciones M×N vs M+N

Lo que lograste: Pasaste de "MCP es un concepto" a "MCP es algo que funciona en mi terminal." Este primer contacto práctico es la base para todo lo que viene. Ahora cuando leas sobre arquitectura MCP (módulo 2) o primitivas (módulo 3), tendrás un anclaje experiencial que hace todo más concreto.

Qué sigue: Módulo 2

En el Módulo 2 (Arquitectura Host-Client-Server) vas a profundizar en cómo funciona MCP internamente:

• Las 3 capas de la arquitectura y cómo interactúan
• El lifecycle completo de una conexión MCP (desde el handshake hasta el cierre)
• Cómo fluyen los datos end-to-end (formato de mensajes, serialización)
• Cómo Claude Code maneja múltiples MCP servers simultáneamente
• El formato JSON-RPC que usa el protocolo bajo el hood
• Transports: stdio vs HTTP/SSE y cuándo usar cada uno

Pasarás de "sé que funciona" a "entiendo cómo funciona" — el conocimiento que necesitas para construir tus propios MCP servers a partir del módulo 3.

Recursos adicionales

1. Claude Code MCP Configuration - Documentación oficial de MCP en Claude Code
2. Filesystem MCP Server - Código fuente del server que usaste
3. Memory MCP Server - Segundo server que configuraste (opcional)
4. Fetch MCP Server - Tercer server (ejercicio 1)
5. MCP Server Configuration Guide - Guía oficial de configuración
6. MCP Debugging Tips - Para troubleshooting avanzado
7. MCP Inspector - Herramienta de debugging visual (la usarás en módulo 7)