Módulo 8: Proyecto — MCP Server Real

Proyecto Final: MCP Server Real (Production-Ready)

Descripción de la cápsula

Este es el momento. Siete módulos de preparación te trajeron aquí. Aprendiste qué es MCP y por qué importa. Entendiste la arquitectura Host-Client-Server. Dominaste las tres primitivas — Resources, Tools, Prompts. Construiste MCP servers en TypeScript y en Python. Creaste MCP Apps con UI interactivo. Aprendiste a testear, debuggear y configurar servers en Claude Code.

Ahora vas a usar todo eso para construir algo real.

No un ejercicio. No un tutorial guiado. Un MCP server production-ready que conecta Claude Code con una database o API real — algo que vas a seguir usando después de completar esta guía.

Por qué un proyecto integrador

Los mini-proyectos de los módulos anteriores te dieron piezas: un server mínimo con 3 primitivas (módulo 3), un server TypeScript con tools y resources (módulo 4), un server Python conectado a GitHub API (módulo 5), un MCP App con dashboard (módulo 6), un test suite (módulo 7). Cada pieza resolvía un aspecto aislado.

Este proyecto es donde las piezas se ensamblan. Diseñas la arquitectura desde cero. Implementas todas las primitivas para un caso de uso coherente. Escribes tests que verifican que todo funciona junto. Documentas el server para que cualquiera pueda usarlo. Y lo conectas a Claude Code para demostrar que funciona end-to-end.

La diferencia entre "sé construir un MCP server" y "puedo entregar un MCP server" es exactamente este proyecto.

¿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
  → Módulo 8: Proyecto — MCP Server Real (ESTÁS AQUÍ)

Todo lo que traes

Haz un inventario de lo que ya sabes. Esto no es retórica — cada una de estas habilidades aparece en el proyecto:

Habilidad	Módulo donde la aprendiste	Cómo la usarás
Arquitectura Host-Client-Server	Módulo 2	Diseñar la comunicación entre Claude Code y tu server
Resources (datos contextuales)	Módulo 3	Exponer datos de tu database/API para que Claude Code los lea
Tools (funciones ejecutables)	Módulo 3	Crear operaciones CRUD que Claude Code puede invocar
Prompts (templates reutilizables)	Módulo 3	Definir workflows estandarizados para interacciones comunes
SDK TypeScript o Python	Módulos 4-5	Implementar el server en el lenguaje que prefieras
Validación con Zod/Pydantic	Módulos 4-5	Validar todos los inputs de tools
Patrones async	Módulo 5	Manejar I/O con la database/API
Error handling	Módulos 4-5, 7	Manejar fallos gracefully
Testing (unit + integration)	Módulo 7	Escribir test suite completo
Debugging con MCP Inspector	Módulo 7	Verificar que todo funciona antes de conectar a Claude Code
Configuración en Claude Code	Módulo 7	Conectar tu server y usarlo end-to-end

Estás listo.

Qué vas a construir

El concepto

Un MCP server completo que conecta Claude Code con una fuente de datos real. Al terminar, podrás abrir Claude Code y hacer cosas como:

"Muéstrame todos los usuarios activos de la base de datos"
"Crea un nuevo proyecto con estos datos"
"Genera un reporte de las tareas completadas esta semana"
"Analiza la estructura de la tabla orders y sugiere índices"

Claude Code usará tu MCP server para ejecutar estas operaciones. No un server genérico, no un ejemplo de tutorial — algo que tú diseñaste, implementaste, y testeaste.

Requisitos del proyecto

Tu MCP server debe incluir:

Componente	Mínimo	Recomendado
Resources	3	5-8
Tools	5	8-12
Prompts	2	3-5
Test suite	Unit tests para cada tool	Unit + integration tests
Documentación	README con setup	README + API reference
Error handling	Try/catch en cada operación	Logging + errores descriptivos

Entregables

Al final del módulo 8, entregas:

Código fuente del MCP server completo
Test suite que pasa con pytest (o vitest)
README.md con instrucciones de setup, uso, y referencia de API
Demo de Claude Code usando tu server en al menos 5 escenarios reales
Reflexión sobre decisiones de diseño y trade-offs

Las 3 opciones de proyecto

Tienes tres caminos. Elige el que mejor se alinee con tu stack, tus intereses, o tu trabajo actual.

Opción A: SQLite + MCP Server Python

Para quién: Estudiantes del Backend Python path, o cualquiera que quiera trabajar con una database local.

Stack:

Python 3.11+
MCP SDK Python (mcp[cli])
SQLite (incluido en Python)
Pydantic para validación
pytest para testing

Qué construyes: Un MCP server que expone una base de datos SQLite completa a Claude Code. Claude Code puede consultar tablas, crear registros, ejecutar queries, y obtener reportes — todo a través de tu server.

Ejemplo de dominio: Sistema de gestión de tareas, inventario de productos, catálogo de cursos, registro de gastos.

Por qué elegir esta opción:

No necesitas instalar nada extra (SQLite viene con Python)
Database local = cero latencia de red
Ideal si vienes del Backend Python Bootcamp
Control total sobre los datos
Más fácil de testear (database en memoria para tests)

Ejemplo concreto de lo que Claude Code podría hacer con tu server:

Tú: "¿Cuántas tareas se completaron esta semana?"
Claude Code: [usa tool query_records] → "Se completaron 14 tareas esta semana.
Las más recientes: 'Migrar database a v2', 'Actualizar dependencias',
'Escribir tests de integración'..."

Complejidad: ⭐⭐⭐ (media)

Opción B: File System + MCP Server TypeScript

Para quién: Estudiantes que prefieren TypeScript, o que quieren un server que interactúe con archivos locales.

Stack:

Node.js 18+
MCP SDK TypeScript (@modelcontextprotocol/sdk)
File system (fs/promises)
Zod para validación
Vitest para testing

Qué construyes: Un MCP server que expone operaciones de file system a Claude Code. Claude Code puede listar directorios, leer archivos, buscar contenido, analizar estructuras de proyecto, y generar reportes sobre codebases.

Ejemplo de dominio: Explorador de proyectos, analizador de codebase, gestor de documentación, organizador de archivos.

Por qué elegir esta opción:

TypeScript es el lenguaje principal del ecosistema MCP
File system = datos locales, sin setup de database
Útil como herramienta real para tu workflow de desarrollo
Zod schemas te dan tipado fuerte end-to-end

Ejemplo concreto de lo que Claude Code podría hacer con tu server:

Tú: "Analiza la estructura de mi proyecto en /Users/me/my-app"
Claude Code: [usa tool analyze_project_structure] → "Tu proyecto tiene 47 archivos
en 12 directorios. Stack principal: TypeScript (68%), CSS (22%), HTML (10%).
Estructura: monorepo con src/, tests/, docs/. 3 archivos sin usar detectados..."

Complejidad: ⭐⭐⭐ (media)

Opción C: API Externa + MCP Server (cualquier lenguaje)

Para quién: Estudiantes que quieren integrar un servicio existente que ya usan.

Stack:

Python o TypeScript (tu elección)
MCP SDK correspondiente
API REST externa (GitHub, Notion, Jira, Todoist, Weather, etc.)
httpx (Python) o fetch (TypeScript) para HTTP
Testing framework correspondiente

Qué construyes: Un MCP server que conecta Claude Code con una API externa real. Similar al proyecto del módulo 5 (GitHub Explorer) pero más completo: más tools, más resources, prompts, tests, documentación.

Ejemplo de dominio: Gestión de proyectos (Jira/Todoist), documentación (Notion), CI/CD (GitHub Actions), monitoreo, CRM.

Por qué elegir esta opción:

Integras algo que ya usas en tu trabajo
Valor práctico inmediato
Experiencia con autenticación y APIs reales
El server es inmediatamente útil después de la guía

Ejemplo concreto de lo que Claude Code podría hacer con tu server:

Tú: "¿Qué issues tiene asignados el equipo de frontend esta semana?"
Claude Code: [usa tool list_issues con filtro] → "El equipo de frontend tiene
8 issues abiertos: 3 bugs (P1), 2 features (P2), 3 improvements (P3).
El issue más urgente es 'Fix login redirect loop' asignado a @mary..."

Complejidad: ⭐⭐⭐⭐ (media-alta, por la dependencia de API externa)

¿Cuál elegir?

Si...	Elige
Vienes del Backend Python Bootcamp	Opción A
Prefieres TypeScript y quieres algo útil para coding	Opción B
Quieres integrar un servicio que ya usas diariamente	Opción C
No sabes cuál elegir	Opción A (la guía usa esta como ejemplo principal)

Esta guía usa la Opción A (SQLite + Python) como ejemplo principal. Todo el código de las cápsulas 2-4 sigue esta opción. Si eliges B o C, adapta los patrones — la arquitectura es la misma, solo cambia la fuente de datos.

Timeline y milestones

Estructura del proyecto por cápsulas

Cápsula	Qué haces	Duración estimada
02 - Diseño y Arquitectura	Decides qué resources, tools, y prompts exponer. Diseñas schemas. Planificas la estructura del proyecto.	30-45 min
03 - Implementación Core	Implementas el server completo: database, resources, tools, prompts, error handling.	60-90 min
04 - Testing y Documentación	Escribes test suite completo y documentación.	45-60 min
05 - Demo End-to-End	Conectas a Claude Code, haces la demo, checklist final.	30-45 min

Total estimado: 2.5 - 4 horas

Milestones de verificación

Después de cada cápsula, deberías poder verificar que estás en buen camino:

Después de Cápsula 02: Tienes un documento de diseño con todos los resources, tools, y prompts planeados. La estructura de archivos existe (vacía).
Después de Cápsula 03: El server corre y responde en MCP Inspector. Todos los tools y resources funcionan manualmente.
Después de Cápsula 04: pytest (o vitest) pasa con todos los tests. El README está escrito.
Después de Cápsula 05: Claude Code usa tu server en flujos reales. La demo muestra al menos 5 escenarios.

Rúbrica de evaluación (100 puntos)

1. Resources (15 puntos)

Criterio	Puntos	Descripción
Cantidad suficiente	5	Mínimo 3 resources implementados
URIs bien diseñados	3	URIs descriptivos que siguen convenciones (e.g., `db://tables`, `db://table/{name}/schema`)
Datos reales	4	Los resources retornan datos reales, no hardcodeados
Error handling	3	Manejan errores gracefully (tabla no existe, conexión perdida)

2. Tools (25 puntos)

Criterio	Puntos	Descripción
Cantidad suficiente	5	Mínimo 5 tools implementados
CRUD completo	5	Al menos create, read, update, delete para una entidad
Validación de inputs	5	Todos los tools validan inputs con Pydantic/Zod
Descripciones claras	3	Cada tool tiene descripción que Claude Code puede entender
Error handling	4	Errores descriptivos para cada caso (not found, validation, connection)
Operaciones avanzadas	3	Al menos 1 tool que hace algo más que CRUD básico (query, reporte, análisis)

3. Prompts (10 puntos)

Criterio	Puntos	Descripción
Cantidad suficiente	3	Mínimo 2 prompts implementados
Útiles y reutilizables	4	Los prompts resuelven interacciones reales recurrentes
Parámetros bien definidos	3	Los prompts aceptan parámetros que los hacen flexibles

4. Testing (20 puntos)

Criterio	Puntos	Descripción
Unit tests por tool	8	Cada tool tiene al menos 1 test de happy path y 1 de error
Tests de resources	4	Resources testeados con datos conocidos
Integration tests	5	Al menos 2 tests que verifican flujos completos (crear → leer → actualizar → borrar)
Tests pasan	3	`pytest` o `vitest` ejecuta sin errores

5. Documentación (15 puntos)

Criterio	Puntos	Descripción
README con setup	5	Instrucciones claras para instalar y configurar el server
Referencia de API	5	Lista de todos los tools, resources y prompts con descripción y parámetros
Instrucciones Claude Code	3	Cómo conectar el server a Claude Code
Ejemplos de uso	2	Al menos 3 ejemplos de cómo usar el server

6. Demo End-to-End (10 puntos)

Criterio	Puntos	Descripción
Server conectado a Claude Code	3	El server aparece en `/mcp` con estado "connected"
Flujos reales demostrados	5	Al menos 5 escenarios donde Claude Code usa el server naturalmente
Sin errores en demo	2	La demo funciona sin crashes ni errores

7. Calidad de código (5 puntos)

Criterio	Puntos	Descripción
Type hints / tipado	2	Todo el código usa type hints (Python) o TypeScript strict mode
Estructura de proyecto limpia	2	Archivos organizados, separación de responsabilidades
Sin código muerto	1	No hay funciones sin usar, imports innecesarios, o código comentado

Escala de calificación

Rango	Nivel
90-100	Excepcional — server production-ready, listo para compartir
80-89	Excelente — server completo con buenas prácticas
70-79	Bueno — server funcional con áreas de mejora
60-69	Aceptable — cumple los requisitos mínimos
< 60	Incompleto — necesita trabajo adicional

Tips para un proyecto exitoso

Antes de entrar en diseño e implementación, algunos tips basados en errores comunes:

Elige un dominio que conozcas

Si trabajas con gestión de proyectos, haz un server de gestión de proyectos. Si manejas inventario, haz un server de inventario. Si eres estudiante y organizas tus tareas en un sistema propio, haz un server para eso.

Un dominio que conoces te permite enfocarte en la implementación MCP en vez de perder tiempo entendiendo las reglas de negocio. Sabrás instintivamente qué tools necesitas, qué datos exponer como resources, y qué queries son las más comunes (candidatas a prompts).

Empieza pequeño, expande después

La tentación es diseñar 15 tools desde el principio. Resiste. Empieza con los 5 mínimos. Haz que funcionen end-to-end. Agrega más después si te sobra tiempo.

Un server con 5 tools bien testeados y documentados vale más que uno con 15 tools a medio funcionar.

No ignores los prompts

Los prompts son la primitiva más subestimada. Un buen prompt transforma interacciones de 3 pasos en interacciones de 1 paso. "Usa el prompt weekly_report para la semana del 10 de marzo" es mucho más poderoso que explicarle a Claude Code paso a paso qué datos consultar y cómo formatear el reporte.

Testea mientras implementas, no al final

Cada tool que implementes, escribe su test inmediatamente. No dejes todos los tests para la cápsula 04. Si algo falla, es más fácil detectar el problema cuando acabas de escribir el código.

Lo que NO es este proyecto

Para evitar malentendidos:

No es un tutorial guiado. Las cápsulas 2-4 muestran un ejemplo completo (Opción A), pero tú diseñas e implementas tu propio server. Usa el ejemplo como referencia, no como template a copiar.
No necesita deploy a producción. "Production-ready" significa código robusto con tests y documentación, no que esté corriendo en un servidor en la nube.
No necesita ser enorme. Un server bien diseñado con 5 tools, 3 resources, y 2 prompts es mejor que uno con 20 tools sin tests ni error handling.
No es un examen. La rúbrica es una guía para asegurarte de que tu server está completo. Si algo no aplica a tu caso de uso, documenta por qué.

Antes de empezar: checklist de preparación

Antes de avanzar a la cápsula 02 (diseño), verifica que tienes todo listo:

Opción elegida: Sabes si vas con A (SQLite + Python), B (File system + TypeScript), o C (API externa)
Dominio definido: Tienes una idea de qué datos/operaciones va a manejar tu server (tareas, productos, archivos, API)
Entorno configurado: Python 3.11+ o Node.js 18+ instalado, MCP SDK instalado
MCP Inspector funcional: Puedes ejecutar mcp dev y ver la interfaz de debugging
Claude Code configurado: Puedes ejecutar claude y conectar MCP servers con claude mcp add
Módulo 7 completado: Sabes escribir tests para MCP servers y diagnosticar problemas de conexión

Si algo de esta lista falla, regresa al módulo correspondiente antes de continuar. Este proyecto asume que todo lo anterior funciona.

El arco completo del proyecto

Piénsalo así: en las próximas 4 cápsulas vas a recorrer el mismo proceso que un developer profesional sigue cuando construye una integración real:

Diseño antes de código — Decides qué exponer, cómo organizar los datos, y qué problemas resolver. Planificas antes de escribir la primera línea.
Implementación incremental — Construyes el server pieza por pieza: primero la database, luego resources, tools, prompts. Cada paso es verificable.
Testing como red de seguridad — Escribes tests que te permiten refactorizar con confianza. Si algo se rompe, lo sabes inmediatamente.
Demo como validación — Conectas todo a Claude Code y demuestras que funciona en el mundo real, no solo en tests aislados.

Este proceso no es ceremonial. Es cómo se construyen herramientas confiables. Y al final de este módulo, tú habrás construido una.

Estructura del módulo

Cápsula 01: Introducción al proyecto (ESTÁS AQUÍ)
  → Scope, opciones, requisitos, rúbrica, timeline

Cápsula 02: Diseño y Arquitectura
  → Qué resources, tools, prompts exponer
  → Schema design, estructura de archivos
  → Ejemplo completo para cada opción

Cápsula 03: Implementación Core
  → Implementación completa de Opción A (SQLite + Python)
  → Database setup, resources, tools, prompts, error handling
  → Código completo y ejecutable

Cápsula 04: Testing y Documentación
  → Test suite completo con pytest
  → README template
  → Documentación de API

Cápsula 05: Demo End-to-End
  → Configurar en Claude Code
  → 5 escenarios de uso real
  → Checklist final, retrospectiva, qué sigue

Cada cápsula depende de la anterior. No saltes.

Resumen

Este módulo es el proyecto integrador de toda la guía — 5 cápsulas construyendo un MCP server real
Integra los 7 módulos anteriores: protocolo, arquitectura, primitivas, SDKs, testing y debugging
El server usa SQLite como database y expone Resources, Tools y Prompts completos
Se evalúa con una rúbrica de 100 puntos que cubre código, testing, documentación y funcionalidad
El proyecto pasa por 4 fases: diseño → implementación → testing/docs → demo end-to-end
Al terminar tendrás un MCP server production-ready que funciona en Claude Code

Recursos

MCP Python SDK — SDK oficial para Python
MCP TypeScript SDK — SDK oficial para TypeScript
SQLite Documentation — Referencia de SQLite
Pydantic v2 Documentation — Validación y serialización en Python
MCP Inspector — Herramienta de debugging visual
Claude Code MCP Configuration — Documentación oficial de MCP en Claude Code

← AnteriorTroubleshooting y Errores Comunes Siguiente →Diseño y Arquitectura del MCP Server