Módulo 7: Testing, Debugging e Integración

Descripción de la cápsula

Tienes MCP servers funcionales. En los módulos 4 y 5 construiste servers en TypeScript y Python. En el módulo 6, creaste MCP Apps con output visual. Todo "funciona en tu terminal." Pero hay una pregunta incómoda que probablemente has estado evitando: ¿funciona de verdad?

"Funciona en mi máquina" es el epitafio de los proyectos que mueren en producción. Un MCP server que retorna el resultado correcto con tus datos de prueba, con tu versión de Node, en tu laptop, no es un MCP server confiable — es un prototipo con suerte. El momento en que alguien más lo usa, o tú lo usas un mes después, o Claude Code lo invoca con inputs que no anticipaste, aparecen los bugs que no testeaste, los errores que no logueaste, y las configuraciones que asumiste sin verificar.

Este módulo cierra ese gap. Pasas de "funciona" a "funciona de forma confiable."

La Phase 3 de esta guía se llama Producción por una razón. No es "producción" en el sentido de deploy a un servidor en la nube — es producción en el sentido de que tu MCP server es lo suficientemente robusto para confiar en él. Para que Claude Code lo use en flujos reales sin que te preocupes de que falle silenciosamente, retorne datos incorrectos, o pierda la conexión sin que te enteres.

¿Dónde estamos?

Contexto en la guía

Phase 1: Fundamentos MCP (Módulos 1-3)
  ✅ Módulo 1: Qué es MCP y por qué importa
  ✅ Módulo 2: Arquitectura Host-Client-Server
  ✅ 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 (ESTÁS AQUÍ)
  ○ Módulo 8: Proyecto — MCP Server Real

Lo que ya sabes

De los módulos anteriores traes:

El modelo mental MCP completo — arquitectura Host-Client-Server, protocolo, flujo de datos
Las 3 primitivas — Resources, Tools, Prompts implementados en dos lenguajes
MCP servers funcionales — TypeScript con Zod, Python con decoradores y Pydantic
MCP Apps — servers que retornan UI interactivo
Experiencia con MCP Inspector — lo usaste para probar tus servers manualmente
Experiencia con Claude Code — conectaste servers y verificaste que Claude Code los usa

Lo que falta

Tus servers funcionan, pero no tienes forma de probar automáticamente que siguen funcionando después de un cambio. No tienes logging que te diga qué pasó cuando algo falla. No tienes un proceso sistemático para diagnosticar problemas de conexión con Claude Code. Y no tienes una guía de referencia para los errores más comunes que vas a encontrar en producción.

Este módulo te da todo eso.

Por qué testing no es burocracia

Hay una resistencia natural al testing, especialmente en proyectos personales o de aprendizaje. "Ya probé que funciona, ¿por qué necesito un test?" La respuesta es un escenario que probablemente ya viviste:

El escenario del bug silencioso

Imagina que tu MCP server tiene un tool search_files que busca archivos por nombre. Lo probaste: funciona. Dos semanas después, actualizas una dependencia. Todo compila. Abres Claude Code, le pides que busque un archivo, y Claude te dice "No se encontraron archivos" — pero el archivo existe. ¿Qué pasó?

Sin tests: pasas 30 minutos debuggeando. Revisas el código. Revisas la configuración. Añades console.log por todos lados. Eventualmente descubres que la nueva versión de la dependencia cambió el formato del output, y tu parser espera el formato anterior.

Con tests: ejecutas npm test. Un test falla: "search_files: expected results.length to be > 0, received 0". Sabes exactamente qué tool está roto, qué se esperaba, y qué recibiste. El fix toma 5 minutos.

Esa es la inversión. 10 minutos escribiendo un test te ahorran 30 minutos de debugging. Multiplicado por cada cambio que hagas en la vida del server, los tests se pagan solos muchas veces.

El escenario de Claude Code en producción

Hay un escenario peor: tu MCP server funciona cuando lo pruebas manualmente, pero falla de formas sutiles cuando Claude Code lo usa:

Claude envía un string donde esperabas un número
Claude omite un parámetro que tú creías obligatorio
Claude envía caracteres Unicode que tu parser no maneja
Claude invoca el tool dos veces simultáneamente y tu código no es thread-safe

Estos bugs no aparecen en pruebas manuales porque tú siempre envías datos "razonables." Claude Code no tiene ese sesgo. Un test automatizado que simula inputs edge case detecta estos problemas antes de que Claude Code los encuentre.

Testing como red de seguridad, no como tarea

La mentalidad correcta no es "tengo que escribir tests" sino "quiero una red de seguridad." Cada test es una garantía: "esto funciona." Cuando modificas tu server — añadir un tool, cambiar un schema, actualizar una dependencia — ejecutas los tests y sabes en segundos si rompiste algo.

Es la diferencia entre caminar en una cuerda floja con red y sin red. La cuerda es la misma, pero tu confianza (y tu velocidad) son completamente diferentes.

La matemática del testing en MCP

Para hacerlo concreto, piensa en los números:

Un MCP server típico tiene:
├── 4-6 tools
├── 2-3 resources
├── 2-3 prompts
└── Error handling en cada uno

Sin tests:
├── Cambio en código → ¿Funciona?
├── Prueba manual de cada tool → 2-3 min cada uno
├── Prueba manual de cada resource → 1-2 min cada uno
├── Total por cambio: 15-25 minutos de pruebas manuales
├── Cambios por semana: 5-10
└── Total por semana: 1-4 horas de pruebas manuales

Con tests:
├── Cambio en código → npm test
├── 15-20 tests se ejecutan → 3-5 segundos
├── Resultado: ✅ todo pasa o ❌ test específico falla
├── Total por cambio: 5 segundos
├── Costo inicial: 30-45 minutos escribir el test suite
└── ROI: se paga en la primera semana

Y eso sin contar los bugs que los tests detectan y las pruebas manuales no. El retorno de inversión es claro.

Qué tipo de tests necesita un MCP server

No todos los tests son iguales. Un MCP server necesita tests específicos para su naturaleza como servidor de protocolo:

Tipo de test	Qué verifica	Ejemplo
Unit test de tool	Que el tool retorna el resultado correcto	`search_files("*.ts")` retorna archivos .ts
Unit test de resource	Que el resource expone los datos correctos	`project://status` retorna JSON válido
Validation test	Que inputs inválidos se rechazan	String donde se espera number → error descriptivo
Error handling test	Que errores se manejan sin crash	Archivo inexistente → `isError: true`, no excepción
Integration test	Que el server responde al protocolo	`tools/list` retorna todos los tools registrados

En la cápsula 02, implementas cada uno de estos tipos.

Las tres capas de este módulo

Este módulo cubre tres capas que trabajan juntas:

1. Testing (Cápsula 02)

Escribir tests automatizados para tus MCP servers:

Testing de MCP servers:
├── Unit tests para tools individuales
│   ├── ¿El tool retorna el resultado correcto?
│   ├── ¿El tool maneja inputs inválidos?
│   └── ¿El tool maneja errores del servicio externo?
├── Unit tests para resources
│   ├── ¿El resource retorna los datos esperados?
│   └── ¿El resource maneja URIs inexistentes?
├── Integration tests
│   ├── ¿El server se inicializa correctamente?
│   ├── ¿Las capabilities se anuncian correctamente?
│   └── ¿El flujo request → response funciona end-to-end?
└── Error handling tests
    ├── ¿Los errores se retornan con isError: true?
    ├── ¿Los mensajes de error son descriptivos?
    └── ¿El server se recupera de errores sin crash?

2. Debugging (Cápsula 03)

Herramientas y técnicas para cuando algo no funciona:

Debugging de MCP servers:
├── MCP Inspector
│   ├── Testing interactivo de tools y resources
│   ├── Inspección de requests y responses
│   └── Verificación de capabilities
├── Logging
│   ├── Qué loguear (requests, errors, timing)
│   ├── Cómo loguear (sin romper el protocolo stdio)
│   └── Niveles de logging
└── Tracing
    ├── Seguir un request a través del server
    ├── Medir tiempos de respuesta
    └── Identificar bottlenecks

3. Integración con Claude Code (Cápsulas 04-05)

Conectar tu server a Claude Code y resolver problemas:

Integración con Claude Code:
├── Configuración
│   ├── Settings files (user vs project)
│   ├── Formatos de configuración
│   ├── Permisos y scopes
│   └── Múltiples servers
├── Verificación
│   ├── ¿Claude Code ve tu server?
│   ├── ¿Claude Code puede invocar tus tools?
│   └── ¿Los resultados son correctos?
└── Troubleshooting
    ├── Connection errors
    ├── Permission denied
    ├── Tool not found
    ├── Timeout
    └── Invalid response format

Objetivo del módulo

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

✅ Escribir unit tests para tools y resources de MCP usando Vitest (TypeScript) y pytest (Python)
✅ Escribir integration tests que verifican el flujo completo client-server
✅ Usar MCP Inspector para debugging visual e interactivo
✅ Implementar logging efectivo en MCP servers sin romper el protocolo stdio
✅ Configurar MCP servers en Claude Code — settings, permisos, verificación
✅ Diagnosticar y resolver los errores más comunes de conexión y ejecución
✅ Construir un test suite completo como el que necesitarás en el proyecto del Módulo 8

Roadmap del módulo

Cápsula	Tema	Qué aprenderás
02	Testing MCP Servers	Unit tests, integration tests, error handling tests con Vitest y pytest
03	Debugging: Herramientas	MCP Inspector avanzado, logging, tracing de requests
04	Configurar Claude Code	Settings files, scopes, permisos, verificación, múltiples servers
05	Troubleshooting y Errores	Errores comunes, diagnóstico, soluciones + mini-proyecto: test suite completo

Flujo de aprendizaje

La progresión es deliberada:

Testing (cápsula 02) — primero aprendes a verificar que tu código funciona. Sin tests, no puedes confiar en que los cambios de las cápsulas siguientes no rompen nada.
Debugging (cápsula 03) — cuando un test falla, necesitas herramientas para encontrar el problema. MCP Inspector y logging son tus aliados.
Configurar Claude Code (cápsula 04) — con tests que pasan y herramientas de debugging listas, conectas tu server a Claude Code. Si algo falla, ya sabes cómo diagnosticarlo.
Troubleshooting (cápsula 05) — la guía de referencia para los problemas que encontrarás en la vida real, más un mini-proyecto que integra todo.

Cada cápsula se apoya en la anterior. Los tests de la cápsula 02 te sirven para verificar que la configuración de la cápsula 04 funciona. El logging de la cápsula 03 te ayuda a resolver los errores de la cápsula 05.

El arco completo: de la Phase 2 a la Phase 3

Para que entiendas la magnitud de la transición:

Phase 2 — "Puedo construir un MCP server":
├── Servidor funcional ✅
├── Tools que retornan resultados ✅
├── Resources que exponen datos ✅
├── MCP Inspector para testing manual ✅
├── Tests automatizados ❌
├── Logging para diagnóstico ❌
├── Configuración verificada en Claude Code ❌
├── Troubleshooting documentado ❌
└── Confianza para usar en flujos reales ❌

Phase 3 — "Puedo confiar en mi MCP server":
├── Todo lo anterior ✅
├── Test suite automatizado ✅
├── Logging que registra requests y errores ✅
├── Configuración de Claude Code verificada ✅
├── Guía de troubleshooting para errores comunes ✅
└── Confianza para usar en producción ✅

La Phase 3 no cambia tu código — cambia tu confianza en tu código. Y esa confianza viene de evidencia: tests que pasan, logs que confirman, y configuraciones que verificas.

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

El Módulo 8 te pide construir un MCP server production-ready. "Production-ready" significa, entre otras cosas:

Test suite completo — unit tests + integration tests
Logging — saber qué pasó cuando algo falla
Configuración verificada — Claude Code conectado y funcionando
Error handling robusto — mensajes claros, recuperación de errores

Todo esto lo aprendes en este módulo. El test suite que escribes en la cápsula 05 (mini-proyecto) es el template para el test suite del Módulo 8. La configuración de Claude Code que haces en la cápsula 04 es la misma que necesitas en el proyecto final.

Módulo 7 → Módulo 8:
├── Tests (cápsula 02)              → Test suite del proyecto
├── Logging (cápsula 03)            → Logging del server en producción
├── Configuración Claude Code (04)  → Setup final del proyecto
├── Troubleshooting (cápsula 05)    → Referencia para resolver problemas
└── Mini-proyecto (cápsula 05)      → Template para test suite del proyecto

Si haces bien este módulo, el Módulo 8 es ensamblaje. Si te lo saltas, el Módulo 8 es una carrera de obstáculos.

Herramientas que usarás en este módulo

Herramienta	Para qué la usas
Vitest	Framework de testing para TypeScript/JavaScript
pytest	Framework de testing para Python
MCP Inspector	Debugging visual e interactivo de MCP servers
Claude Code	El host que consume tu MCP server
Node.js / Python	Runtimes de tus MCP servers
npx	Ejecutar MCP Inspector sin instalación global

No necesitas instalar todo ahora — cada cápsula te guía paso a paso.

Prerequisitos

Para este módulo necesitas:

✅ Módulos 4-6 completados — al menos un MCP server funcional en TypeScript o Python
✅ Node.js v18+ — node --version
✅ Python 3.10+ (si usas Python) — python --version
✅ Claude Code instalado — claude --version
✅ Un MCP server propio para testear y debuggear

Conocimiento previo

No necesitas experiencia previa con testing frameworks. La cápsula 02 empieza desde cero con Vitest y pytest. Si ya tienes experiencia con testing, vas a avanzar más rápido, pero no es requerido.

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

❌ Deploy a cloud — El deploy a producción (cloud, Docker) no es parte del scope de esta guía
❌ CI/CD pipelines — La integración continua es tema de otra guía
❌ Performance testing — Load testing y benchmarks están fuera del scope
❌ Security testing — Penetration testing y security audits son temas especializados
❌ Testing de MCP Apps UI — El testing de interfaces visuales requiere herramientas específicas
❌ Testing de transports remotos — HTTP/SSE testing requiere setup de infraestructura adicional

Este módulo cubre testing funcional, debugging, y configuración. Es lo que necesitas para pasar de "funciona" a "funciona de forma confiable."

Comparación de herramientas de testing

Antes de empezar, un overview de las herramientas que usarás y por qué:

Para TypeScript: Vitest

¿Por qué Vitest y no Jest?
├── Compatibilidad nativa con TypeScript (sin configuración extra)
├── ESM support out of the box (MCP SDK usa ESM)
├── Más rápido que Jest para proyectos TypeScript
├── API compatible con Jest (si ya conoces Jest, sabes Vitest)
└── watch mode para desarrollo iterativo

Para Python: pytest

¿Por qué pytest y no unittest?
├── Sintaxis más limpia (funciones, no clases)
├── Fixtures para setup/teardown reutilizable
├── Plugins para async testing (pytest-asyncio)
├── Mejor output de errores
└── Estándar de facto en la comunidad Python

Ambas herramientas se configuran desde cero en la cápsula 02. No necesitas experiencia previa con ninguna.

Evidencia de éxito

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

✅ Tienes un test suite con al menos 10 tests para un MCP server (tools + resources + error handling)
✅ Puedes usar MCP Inspector para diagnosticar por qué un tool no funciona
✅ Tu MCP server tiene logging que te dice qué requests recibió y qué errores encontró
✅ Claude Code tiene tu server configurado y puedes verificarlo con /mcp
✅ Puedes diagnosticar y resolver los 5 errores más comunes sin buscar en Google
✅ Puedes ejecutar npm test o pytest y ver todos tus tests pasar en verde

Mentalidad para este módulo

Este módulo requiere un cambio de mentalidad. En los módulos 4-6, el feedback era inmediato y visual: corres el server, abres MCP Inspector, ves que funciona, satisfacción. Testing y debugging son diferentes: el feedback es menos visible pero más valioso.

Tres principios:

Un test que falla es más valioso que un test que pasa. Cuando un test falla, encontraste un bug antes de que Claude Code lo encontrara. Eso es una victoria.
Logging no es debugging — es prevención. No añades logging cuando tienes un bug. Añades logging antes, para que cuando el bug aparezca, el log te diga exactamente dónde está.
La configuración de Claude Code es el momento de verdad. Todo el trabajo de los módulos 4-6 converge aquí. Cuando Claude Code invoca tu tool y retorna el resultado correcto, completaste el loop: diseñaste, construiste, testeaste, y conectaste un MCP server. Tú lo construiste, y Claude Code lo usa.

Preguntas frecuentes antes de empezar

"¿Necesito testear en ambos lenguajes (TypeScript y Python)?"

No. Si solo construiste un server en un lenguaje, testea ese. La cápsula 02 muestra Vitest para TypeScript y pytest para Python. Elige el que aplique a tu server. Si construiste en ambos, la cápsula cubre ambos.

"¿MCP Inspector y las pruebas manuales no son suficientes?"

MCP Inspector es excelente para debugging interactivo, pero no es un sustituto de tests automatizados. Inspector te dice "funciona ahora." Tests te dicen "sigue funcionando después de cada cambio." Los necesitas a ambos.

"¿Cuánto tiempo toma escribir un test suite?"

Para un MCP server con 3-4 tools y 2-3 resources, un test suite básico (happy path + error cases) toma ~30-45 minutos. Es una inversión que se paga la primera vez que detecta un bug.

"¿Necesito configurar Claude Code ahora o puedo hacerlo después?"

La cápsula 04 te guía paso a paso. Si ya tienes tu server configurado en Claude Code de módulos anteriores, la cápsula te ayuda a verificar que la configuración es correcta y completa.

Resumen

Este módulo inicia la Phase 3: Producción — de "funciona" a "funciona de forma confiable"
Testing no es burocracia — es una inversión que detecta bugs antes de que Claude Code los encuentre
Tres capas: testing automatizado (Vitest/pytest), debugging (MCP Inspector/logging), integración (configuración Claude Code)
El módulo es prerequisito directo del Módulo 8 — el test suite y la configuración que haces aquí son la base del proyecto integrador
Cada cápsula construye sobre la anterior: tests → debugging → configuración → troubleshooting
La mentalidad es de profesionalismo: "así es como los developers serios aseguran que su código funciona"

Recursos adicionales

Vitest Documentation — Framework de testing que usarás para TypeScript
pytest Documentation — Framework de testing para Python
MCP Inspector — Herramienta de debugging visual para MCP servers
MCP TypeScript SDK — Testing — SDK oficial con ejemplos de testing
MCP Python SDK — SDK oficial para Python
Claude Code MCP Configuration — Documentación oficial de configuración MCP en Claude Code

Siguiente cápsula: Testing MCP Servers — unit tests, integration tests, y error handling tests con Vitest y pytest. Tests reales para MCP servers reales.

← AnteriorProyecto: MCP App con Dashboard Interactivo Siguiente →Testing MCP Servers