Módulo 8: Proyecto — MCP Server Real

Demo End-to-End: Claude Code + Tu MCP Server

Descripción de la cápsula

Tu MCP server tiene código completo, tests que pasan, y documentación. Falta lo más importante: demostrar que funciona en el mundo real. En esta cápsula conectas tu server a Claude Code, lo usas en 5 escenarios reales, haces el checklist final, y reflexionas sobre lo que construiste.

Esta cápsula es también una celebración. Construiste un MCP server production-ready desde cero. Eso no es trivial. Tomemos un momento para apreciar lo que eso significa.

Paso 1: Configurar el server en Claude Code

Registrar el server

Abre tu terminal y registra el server con Claude Code:

claude mcp add task-manager \
  /ruta/completa/task-manager-mcp/.venv/bin/python \
  -e PYTHONPATH=/ruta/completa/task-manager-mcp \
  -- /ruta/completa/task-manager-mcp/src/server.py

Reemplaza /ruta/completa/task-manager-mcp con la ruta real a tu proyecto. Puedes obtenerla con pwd dentro del directorio del proyecto.

Para Opción B (TypeScript):

claude mcp add project-analyzer \
  node \
  -- /ruta/completa/project-analyzer/dist/index.js

Para Opción C (API externa):

claude mcp add todoist-integration \
  -e TODOIST_API_KEY=tu_token_aqui \
  /ruta/completa/.venv/bin/python \
  -e PYTHONPATH=/ruta/completa/todoist-mcp \
  -- /ruta/completa/todoist-mcp/src/server.py

Verificar la conexión

claude

Dentro de Claude Code:

> /mcp

Deberías ver:

task-manager
  Status: connected
  Tools: create_task, list_tasks, update_task, delete_task, search_tasks,
         create_category, run_query, get_task_summary
  Resources: taskdb://tables, taskdb://table/{table_name}/schema,
             taskdb://stats, taskdb://tasks/overdue, taskdb://categories
  Prompts: analyze_table, weekly_report, optimize_query

Si el status es "connected" y ves todos los tools, resources, y prompts, la conexión es exitosa. Este es el momento donde todo lo que construiste se materializa — tu código pasó de ser archivos en disco a ser capabilities que Claude Code puede usar.

Tómate un momento para apreciar esto. Escribiste un server. Lo registraste en Claude Code. Y ahora Claude Code sabe hacer cosas que no sabía hacer antes — porque tú le diste esas capabilities.

Si la conexión falla

"Status: error" o "Status: disconnected":

# Verificar que el server corre standalone
cd /ruta/completa/task-manager-mcp
source .venv/bin/activate
PYTHONPATH=. python src/server.py

Si el server da error standalone, hay un problema en tu código (probablemente un import error). Arréglalo antes de continuar.

"No tools found":

El server se conectó pero no registró nada. Verifica que src/server.py llama a mcp.tool(), mcp.resource(), y @mcp.prompt() correctamente. Ejecuta en MCP Inspector para diagnosticar.

"Permission denied":

Verifica que el path al Python del virtualenv es correcto y tiene permisos de ejecución:

ls -la /ruta/completa/task-manager-mcp/.venv/bin/python

Paso 2: Demo — 5 escenarios reales

Ahora la parte divertida. Vas a usar tu MCP server en 5 escenarios que demuestran diferentes capabilities. Cada escenario muestra un aspecto distinto del server.

Escenario 1: Explorar la base de datos

Lo que demuestras: Resources funcionan — Claude Code puede leer la estructura de tu database.

Dentro de Claude Code:

> ¿Qué tablas tiene mi base de datos de tareas? Dame la estructura de cada una.

Lo que debería pasar:

Claude Code lee el resource taskdb://tables para ver las tablas disponibles
Claude Code lee taskdb://table/tasks/schema, taskdb://table/categories/schema, etc.
Claude Code te presenta un resumen claro de la estructura

Resultado esperado: Claude Code muestra las 4 tablas (tasks, categories, tags, task_tags) con sus columnas, tipos, y relaciones. Algo como:

Tu base de datos tiene 4 tablas:

1. **tasks** (10 registros) — La tabla principal con campos: id, title,
   description, status, priority, category_id, due_date, created_at, updated_at

2. **categories** (4 registros) — Categorías: id, name, description, color

3. **tags** (5 registros) — Tags: id, name

4. **task_tags** — Relación muchos-a-muchos entre tasks y tags

Si falla: El resource taskdb://tables no está retornando datos. Verifica en MCP Inspector que el resource responde y que la database tiene datos (seed data).

Por qué este escenario importa: Demuestra la base de todo — que Claude Code puede entender la estructura de tus datos antes de operar con ellos. En el mundo real, un developer le pediría a Claude Code "entiende esta database" como primer paso antes de hacer queries o crear código.

Escenario 2: Gestión de tareas (CRUD)

Lo que demuestras: Tools de creación, lectura, actualización y eliminación funcionan end-to-end.

Dentro de Claude Code, haz una secuencia de requests:

Request 1 — Crear:

> Crea una tarea "Preparar presentación del MCP server" con prioridad alta,
  categoría DevOps, y fecha límite el 25 de marzo de 2026. Agrégale los tags
  "demo" y "presentación".

Claude Code debería usar create_task y confirmar la creación con el ID asignado.

Request 2 — Listar:

> Muéstrame todas las tareas de prioridad alta

Claude Code debería usar list_tasks con filtro de prioridad y mostrar las tareas, incluyendo la que acabas de crear. Verifica que la nueva tarea aparece en la lista.

Request 3 — Actualizar:

> Cambia el estado de la tarea "Preparar presentación del MCP server" a en progreso

Claude Code debería usar update_task para cambiar el status a in_progress.

Request 4 — Verificar:

> ¿Cuál es el estado actual de mis tareas? Dame un resumen rápido.

Claude Code podría usar get_task_summary o list_tasks para mostrar el estado actual, donde la tarea de la presentación aparece como "in_progress".

Escenario 3: Búsqueda y análisis

Lo que demuestras: Tools de búsqueda y queries custom funcionan con datos reales.

Request 1 — Buscar:

> Busca tareas que mencionen "bug" o "fix" en el título o la descripción

Claude Code debería usar search_tasks y encontrar la tarea "Fix pagination bug" del seed data.

Resultado esperado: Claude Code retorna la tarea con su información completa, incluyendo que ya tiene status "completed" y prioridad "critical".

Request 2 — Query custom:

> Ejecuta una query para ver cuántas tareas hay por cada estado y prioridad

Claude Code debería usar run_query con algo como:

SELECT status, priority, COUNT(*) as count
FROM tasks
GROUP BY status, priority
ORDER BY status, priority

Request 3 — Análisis con datos:

> ¿Cuáles son las tareas vencidas que necesitan atención urgente?

Claude Code podría usar el resource taskdb://tasks/overdue o el tool run_query para encontrar tareas con due_date pasado.

Resultado esperado: Claude Code identifica las tareas con due_date anterior a hoy y status diferente de "completed" o "cancelled", mostrando cuántos días de retraso tiene cada una.

Por qué este escenario importa: Demuestra que tu server puede responder preguntas de negocio — no solo hacer CRUD. La diferencia entre un MCP server útil y uno mediocre es que el útil responde preguntas que importan.

Escenario 4: Usar prompts

Lo que demuestras: Los prompts estandarizan interacciones complejas.

Request 1 — Análisis de tabla:

> Usa el prompt analyze_table para analizar la tabla tasks

Claude Code debería ejecutar el prompt analyze_table, que internamente:

Lee el schema de la tabla
Consulta el conteo de registros
Ve una muestra de datos
Genera un análisis completo con recomendaciones

Resultado esperado: Un análisis detallado que incluye la estructura de la tabla, distribución de datos por status y prioridad, y sugerencias de índices o mejoras.

Request 2 — Reporte semanal:

> Genera un reporte semanal de productividad

Claude Code debería ejecutar el prompt weekly_report, que combina múltiples tools y resources para generar un reporte completo.

Resultado esperado: Un reporte estructurado con tareas completadas, pendientes, vencidas, y recomendaciones. El reporte debería sentirse como algo que un project manager generaría — no como un JSON dump.

Por qué los prompts son poderosos: Sin el prompt, tendrías que decirle a Claude Code paso por paso qué consultar y cómo formatearlo. Con el prompt, una sola frase genera un reporte completo. Esa es la diferencia entre una herramienta y una plataforma.

Escenario 5: Flujo multi-paso complejo

Lo que demuestras: Claude Code puede encadenar múltiples tools y resources en un flujo natural.

> Quiero reorganizar mis tareas. Primero muéstrame las categorías que existen
  y cuántas tareas tiene cada una. Luego crea una nueva categoría llamada "Urgente"
  con color rojo (#FF0000). Después, muéstrame las tareas de prioridad "critical"
  y sugiere cuáles deberían moverse a la categoría "Urgente".

Lo que debería pasar:

Claude Code lee taskdb://categories para ver las categorías actuales
Claude Code usa create_category para crear "Urgente"
Claude Code usa list_tasks con filtro de prioridad critical
Claude Code analiza las tareas y sugiere cuáles mover

Este escenario demuestra que tu server soporta flujos complejos donde Claude Code toma decisiones basadas en datos de tu database. Es el escenario más cercano a un uso real en producción — donde no le pides "ejecuta este tool específico" sino que describes un objetivo y Claude Code decide cómo usar las herramientas disponibles.

Por qué es el escenario más importante: En el mundo real, tus requests a Claude Code serán así: complejos, multi-paso, con decisiones intermedias. Si tu server soporta este tipo de flujo, soporta cualquier cosa.

Paso 3: Evaluar la calidad de la demo

Después de cada escenario, evalúa no solo si "funcionó" sino qué tan bien funcionó:

Criterios de evaluación por escenario

¿Claude Code eligió los tools correctos? Si Claude Code usa un tool diferente al esperado pero llega al resultado correcto, eso es un éxito — demuestra que tus descriptions son buenas y que el modelo entiende las capacidades de tu server.

Si Claude Code no usa ningún tool de tu server (y responde con conocimiento general), algo falla en la conexión o en las descriptions.

¿Los resultados son correctos? Verifica manualmente que los datos que Claude Code presenta corresponden a los datos reales en tu database. Un tool que retorna datos incorrectos es peor que uno que falla — porque no te das cuenta del error.

¿Los errores se comunican bien? Prueba provocar un error intencionalmente (e.g., pide borrar una tarea con ID 99999). Claude Code debería comunicar el error de forma clara, no mostrar un stack trace.

¿El flujo se siente natural? Si tienes que explicarle a Claude Code exactamente qué tool usar y con qué parámetros, las descriptions necesitan mejora. Un flujo natural se ve así: tú describes lo que quieres, y Claude Code decide cómo obtenerlo.

Tips para una demo exitosa

Prepara la database con datos interesantes

Los datos de ejemplo del seed son un buen punto de partida, pero agrega datos específicos a tu dominio. Si tu server es de gestión de tareas, agrega tareas reales que tengas pendientes. Datos reales hacen que la demo se sienta auténtica.

Empieza simple, escala la complejidad

No empieces con el escenario 5 (multi-paso complejo). Empieza con el escenario 1 (explorar la DB). Cada escenario que funciona te da confianza para el siguiente. Si algo falla en el escenario 1, es más fácil diagnosticar que si falla en el 5.

Ten MCP Inspector abierto en paralelo

Si algo falla en Claude Code, puedes verificar rápidamente en MCP Inspector si el problema es tu server o la comunicación. MCP Inspector te muestra la respuesta raw de cada tool/resource.

# En una terminal separada
PYTHONPATH=. mcp dev src/server.py

Graba la pantalla (opcional pero recomendado)

Si quieres compartir tu proyecto o simplemente tener un registro, graba la demo. Puedes usar asciinema para grabar la terminal:

asciinema rec demo.cast
# ...hacer la demo...
# Ctrl+D para terminar

No tengas miedo de los errores

Si algo falla durante la demo, trátalo como una oportunidad. ¿El error message es claro? ¿Claude Code lo comunica bien? ¿Puedes diagnosticar y arreglar en el momento? La capacidad de manejar fallos es parte de ser production-ready.

Paso 4: Registrar los resultados de la demo

Después de ejecutar los 5 escenarios, anota los resultados:

Escenario	Resultado	Tools/Resources usados	Notas
1: Explorar DB	✅/❌
2: CRUD tareas	✅/❌
3: Búsqueda y análisis	✅/❌
4: Prompts	✅/❌
5: Flujo multi-paso	✅/❌

Si algún escenario falla, diagnostica:

¿El tool retorna un error? → Revisa el código del tool
¿Claude Code no usa el tool correcto? → Mejora la description del tool
¿El server se desconecta? → Revisa logs con claude mcp add ... 2>&1 | tee server.log
¿El resultado es incorrecto? → Verifica los datos en la database

Checklist final del proyecto

Código (40 puntos de la rúbrica)

Server corre sin errores: PYTHONPATH=. python src/server.py
5+ tools implementados y funcionales
3+ resources implementados y funcionales
2+ prompts implementados y funcionales
Pydantic models con validación para cada tool input
Error handling consistente en todos los tools (try/catch, mensajes descriptivos)
Type hints en todo el código
Sin código muerto, imports innecesarios, o funciones sin usar
Estructura de archivos limpia y organizada

Testing (20 puntos)

PYTHONPATH=. pytest -v pasa todos los tests
Tests de happy path para cada tool
Tests de error cases (ID inexistente, input inválido, query prohibida)
Tests de integración (flujo CRUD completo)
Tests usan database en memoria (no tocan data/tasks.db)

Documentación (15 puntos)

README.md con instrucciones de instalación
Tabla de todos los tools con parámetros
Tabla de todos los resources con URIs
Tabla de todos los prompts
Instrucciones para conectar a Claude Code
Al menos 3 ejemplos de uso

Demo (10 puntos)

Server conectado a Claude Code (status: connected en /mcp)
5 escenarios ejecutados exitosamente
Claude Code usa los tools de forma natural
Sin crashes ni errores durante la demo

Calidad general (15 puntos)

Resources, Tools, y Prompts están correctamente asignados
URIs de resources siguen convenciones claras
Descriptions de tools son claras y útiles para Claude Code
El server resuelve un problema real (no es un toy example)
El proyecto es algo que seguirías usando después de la guía

Escenarios bonus: casos avanzados

Si los 5 escenarios principales funcionaron sin problemas, prueba estos escenarios bonus que demuestran edge cases y robustez:

Bonus 1: Manejo de errores

> Borra la tarea con ID 99999

Claude Code debería usar delete_task y recibir un error "not_found". Verifica que Claude Code comunica el error de forma clara: "La tarea con ID 99999 no existe" — no un stack trace ni un error genérico.

Bonus 2: Query inválida

> Ejecuta esta query: DELETE FROM tasks WHERE status = 'cancelled'

Tu tool run_query debería rechazar la query porque contiene DELETE. Claude Code debería explicar que solo queries SELECT están permitidas.

Bonus 3: Datos especiales

> Crea una tarea "Revisar artículo: 'Cómo usar MCP en español'" con la descripción
  "Incluir secciones sobre: ñ, acentos (á, é, í, ó, ú) y caracteres especiales"

Verifica que los caracteres Unicode se manejan correctamente — tanto en la creación como en la lectura.

Bonus 4: Uso intensivo

> Crea 5 tareas nuevas: "Tarea Alpha" (prioridad high), "Tarea Beta" (prioridad low),
  "Tarea Gamma" (prioridad critical), "Tarea Delta" (prioridad medium),
  "Tarea Epsilon" (prioridad high). Todas en la categoría Backend.

Claude Code debería crear las 5 tareas una por una (o pedir aprobación para cada una). Verifica que todas se crean correctamente.

Después:

> Muéstrame un resumen de todas las tareas, agrupadas por prioridad

Debería incluir las 5 nuevas tareas en los conteos correctos.

Puntuación y autoevaluación

Usa la rúbrica de la cápsula 01 para evaluar tu proyecto. Sé honesto — la autoevaluación es para ti, no para una calificación. El objetivo es identificar áreas donde puedes mejorar.

Sección	Puntos posibles	Tu puntuación
Resources	15	/15
Tools	25	/25
Prompts	10	/10
Testing	20	/20
Documentación	15	/15
Demo	10	/10
Calidad de código	5	/5
Total	100	/100

Retrospectiva

Antes de cerrar el proyecto, tómate 15 minutos para responder estas preguntas. No hay respuestas correctas — es una reflexión para consolidar lo que aprendiste. Escríbelas. El acto de escribir fuerza la reflexión de maneras que "pensarlo" no logra.

Sobre el proceso

¿Qué fue lo más difícil de este proyecto? ¿El diseño? ¿La implementación? ¿Los tests? ¿La configuración de Claude Code? La mayoría de developers dicen que el diseño fue lo más difícil — decidir qué exponer y cómo organizarlo requiere un tipo de pensamiento diferente a escribir código.
¿Qué decisión de diseño cambiarías si empezaras de nuevo? ¿Organizarías los tools diferente? ¿Elegirías otro schema? ¿Agregarías más resources o prompts? No hay un diseño perfecto — pero reflexionar sobre qué cambiarías mejora tu próximo diseño.
¿Qué te sorprendió? ¿Algo fue más fácil o más difícil de lo que esperabas? Muchos developers se sorprenden de lo simple que es registrar tools y resources con FastMCP, y de lo complejo que es escribir buenas descriptions.

Sobre MCP

¿Cuándo usarías resources vs tools? ¿Quedó clara la distinción después de implementar ambos? La regla: si Claude Code lo necesita como contexto para decidir → resource. Si Claude Code lo ejecuta cuando el usuario lo pide → tool.
¿Los prompts son útiles? ¿Los usarías regularmente o solo para demos? Los prompts son más útiles de lo que parecen. Un buen prompt convierte un flujo de 5 requests en 1.
¿Qué tool agregarías si tuvieras más tiempo? ¿Hay una operación que falta y que haría el server más completo? Esta pregunta es la semilla de la próxima iteración de tu server.

Sobre producción

¿Tu server está realmente "production-ready"? ¿Qué le falta para que confíes en él al 100%? Probablemente: autenticación, rate limiting, logging más robusto, backup de database, monitoring.
¿Qué harías diferente con el error handling? ¿Los mensajes de error son suficientemente claros para que Claude Code los comunique bien al usuario? Un buen ejercicio: provoca todos los errores posibles y evalúa si los mensajes son útiles.
¿Los tests cubren los casos importantes? ¿Hay edge cases que no testeaste? Piensa en: inputs vacíos, strings muy largos, caracteres Unicode, requests simultáneos, database llena.

Sobre el path

¿Cómo conecta este proyecto con tu trabajo? ¿Ves aplicaciones de MCP servers en tu contexto profesional? Piensa en las APIs y databases que usas diariamente. ¿Cuáles se beneficiarían de un MCP server?
¿Recomendarías MCP a un colega? ¿Por qué sí o por qué no? ¿Qué le dirías para convencerlo de probarlo?
¿Qué skills de esta guía usarás más frecuentemente? ¿La capacidad de construir servers? ¿Los patrones de testing? ¿El diseño de APIs via MCP?

Qué sigue: más allá de esta guía

Completaste la guía. Tienes un MCP server production-ready que Claude Code usa. Eso es un logro significativo — la mayoría de developers no han construido una integración custom para su AI assistant.

Pero esto es solo el principio. Aquí tienes caminos para seguir creciendo:

Mejorar tu server actual

Antes de construir algo nuevo, tu server actual tiene espacio para crecer:

Más tools:

batch_update_tasks — Actualizar múltiples tareas a la vez (e.g., "marca todas las tareas de la categoría DevOps como completadas")
get_task_history — Si implementas un log de cambios, ver el historial de una tarea
export_data — Exportar datos en CSV o JSON
import_data — Importar tareas desde un archivo

Más resources:

taskdb://tasks/today — Tareas con due_date hoy
taskdb://tasks/recent — Últimas 5 tareas creadas/modificadas
taskdb://health — Health check del server (database accesible, versión, uptime)

Más prompts:

daily_standup — "¿Qué hice ayer? ¿Qué haré hoy? ¿Hay bloqueos?"
sprint_planning — Planifica la próxima semana basándose en tareas pendientes y prioridades
retrospective — Análisis de lo completado vs planeado en un periodo

Features de infraestructura:

Caching para resources que no cambian frecuentemente
Logging estructurado con niveles (debug, info, warning, error)
Métricas de uso (qué tools se usan más, tiempos de respuesta)
Configuración vía variables de entorno (DB path, log level, etc.)

Publicar tu server

GitHub repo público: Comparte tu server para que otros lo usen
README detallado: Los buenos READMEs hacen la diferencia entre un repo que nadie mira y uno con estrellas
PyPI / npm: Publica como paquete instalable
MCP Registry: Si existe un registry centralizado de MCP servers, registra el tuyo

Construir más MCP servers

Ahora que sabes cómo funciona el patrón, puedes construir servers para cualquier servicio:

Servicio	Resources	Tools
Notion	Páginas, databases, bloques	Crear página, actualizar, buscar
Slack	Canales, mensajes recientes	Enviar mensaje, buscar, listar canales
PostgreSQL	Tablas, schemas, métricas	CRUD, queries, migrations
AWS S3	Buckets, objetos, storage stats	Upload, download, list, delete
Docker	Containers, images, volumes	Run, stop, logs, build
Jira	Issues, sprints, boards	Crear issue, asignar, transicionar

Cada uno de estos sigue el mismo patrón que usaste en este proyecto:

Define el dominio y las operaciones
Mapea a resources, tools, y prompts
Implementa con el SDK
Testea
Conecta a Claude Code
Documenta

El patrón se repite. Lo que cambia son los datos y las operaciones. Tu segundo MCP server te tomará la mitad del tiempo que el primero.

Explorar features avanzadas de MCP

Sampling: El server pide al host que genere texto con el LLM (loop inverso)
Roots: Definir directorios que el server puede acceder (sandboxing)
SSE Transport: Servers remotos accesibles via HTTP (no solo stdio local)
Multi-server: Claude Code usando múltiples MCP servers simultáneamente
Custom notifications: El server notifica al host de cambios en datos

Contribuir al ecosistema

Reportar bugs: Si encuentras problemas con el SDK, abre issues en GitHub
Mejorar documentación: Los SDKs son nuevos — toda contribución a docs ayuda
Open source servers: Contribuye a MCP servers existentes o crea nuevos para servicios populares
Comunidad: Comparte lo que aprendiste — blog posts, talks, tutorials
Mentorear: Ayuda a otros developers a crear su primer MCP server — tú ya sabes cómo

El mapa completo: de dónde vienes

Hagamos un recuento de todo lo que lograste en esta guía. Cada módulo construyó sobre el anterior, y este proyecto integró todo:

Módulo 1: Entendiste el problema

El problema M×N de integraciones y cómo MCP lo resuelve con el modelo M+N. La analogía USB-C. El ecosistema.

Módulo 2: Entendiste la arquitectura

Host → Client → Server. El flujo completo de un request. Roles y responsabilidades de cada componente.

Módulo 3: Dominaste las primitivas

Resources para datos contextuales. Tools para operaciones con side effects. Prompts para templates reutilizables.

Módulo 4: Construiste en TypeScript

MCP server con SDK TypeScript. Zod schemas. Transports (stdio, HTTP/SSE).

Módulo 5: Construiste en Python

MCP server con FastMCP y decoradores. Pydantic. Patrones async. GitHub API.

Módulo 6: Creaste MCP Apps

UI interactivo como output de tools. Dashboards. Forms.

Módulo 7: Profesionalizaste

Testing con Vitest y pytest. Debugging con MCP Inspector. Configuración en Claude Code. Troubleshooting.

Módulo 8: Construiste algo real

Un MCP server production-ready conectado a una database real. Con tests. Con documentación. Funcionando en Claude Code.

En números

Piensa en lo que tu proyecto incluye:

8+ tools que Claude Code puede invocar
5+ resources que Claude Code puede leer para contexto
3 prompts que automatizan flujos complejos
30+ tests que verifican que todo funciona
1 README que permite a cualquiera instalar tu server
1 database con datos reales
5 escenarios demostrados end-to-end

Eso no es un ejercicio de tutorial. Eso es una integración custom funcional.

El momento "yo construí eso"

Abre Claude Code. Hazle una pregunta que solo tu MCP server puede responder. Mira cómo usa tu tool. Mira cómo retorna datos de tu database. Mira cómo sigue el template de tu prompt.

Tú construiste eso.

No copiaste un tutorial. No instalaste el server de alguien más. Diseñaste la arquitectura, escribiste el código, testeaste cada pieza, documentaste todo, y lo conectaste a Claude Code.

Claude Code ahora puede hacer cosas que no podía hacer antes — porque tú le diste esas capabilities.

Ese es el poder de MCP. Cada developer que entiende el protocolo puede extender lo que un AI assistant puede hacer. Puede convertir cualquier API, cualquier database, cualquier servicio, en algo que el AI usa nativamente.

Y ahora tú sabes cómo hacerlo.

Antes y después

Piensa en dónde estabas al inicio de esta guía vs dónde estás ahora:

Antes	Después
"MCP es... ¿algo de Anthropic?"	"MCP es el protocolo estándar que conecta AI hosts con servicios externos"
"Claude Code solo puede leer y escribir archivos"	"Claude Code puede hacer cualquier cosa para la que tenga un MCP server"
"No sé cómo extender mi AI assistant"	"Puedo construir un MCP server para cualquier API o database"
"Los tools son magia negra del framework"	"Los tools son funciones Python con validación Pydantic que registro con un decorador"
"Testing de integraciones AI es imposible"	"Uso databases en memoria y patches para testear cada tool"
"Production-ready significa deploy a la nube"	"Production-ready significa código robusto, tests, documentación, y error handling"

Esa transformación es el objetivo de esta guía. Y la evidencia de que la completaste está corriendo en tu Claude Code ahora mismo.

Compartir tu proyecto

Si quieres compartir tu proyecto (y deberías), aquí están los pasos:

Preparar para GitHub

cd task-manager-mcp

# Verificar que .gitignore está bien
cat .gitignore

# Inicializar repo si no lo tienes
git init
git add .
git commit -m "MCP server: task manager con SQLite"

Checklist antes de publicar

.gitignore incluye .venv/, __pycache__/, data/tasks.db
No hay tokens ni credenciales en el código
README.md tiene instrucciones de instalación completas
Los tests pasan en un entorno limpio (clona el repo y prueba)
El seed data no contiene información personal

¿Por qué compartir?

Portfolio: Un MCP server funcional demuestra habilidades técnicas concretas
Feedback: Otros developers pueden encontrar bugs o sugerir mejoras
Comunidad: El ecosistema MCP crece cuando más developers publican servers
Referencia futura: Tu yo del futuro te agradecerá tener un ejemplo completo documentado

Troubleshooting de la demo

"Claude Code no usa el tool que esperaba"

Claude Code elige qué tool usar basándose en tu request y las descriptions de los tools. Si no usa el tool correcto:

Sé más explícito: "Usa el tool search_tasks para buscar..."
Mejora la description del tool — agrega más contexto sobre cuándo usarlo
Revisa el campo instructions del FastMCP() — le dice al modelo qué puede hacer tu server

"El server se desconecta durante la demo"

Tu server probablemente tiene un error que causa un crash. Para diagnosticar:

# Verificar que el server corre standalone
cd task-manager-mcp
PYTHONPATH=. python src/server.py

Si hay un error de import o de inicialización, aparece aquí. Arréglalo y reconecta:

claude mcp remove task-manager
claude mcp add task-manager ...

"Claude Code pide permiso para cada tool"

Es el comportamiento esperado. Claude Code pide aprobación antes de ejecutar tools (porque tienen side effects). Puedes aprobar con "y" o "a" (yes / allow). Para aprobar todos los tools de una sesión, usa "a" en la primera invocación.

"Los datos no reflejan los cambios que hice"

Tu server usa SQLite con WAL mode. Los cambios deberían reflejarse inmediatamente. Si no:

Verifica que el get_connection hace conn.commit() (el context manager lo hace automáticamente)
Verifica que no hay otra instancia del server leyendo una database diferente
Ejecuta run_query con SELECT * FROM tasks ORDER BY id DESC LIMIT 5 para ver los datos más recientes

"Los prompts no hacen lo que esperaba"

Los prompts generan texto que instruye a Claude Code sobre qué tools y resources usar. Si el resultado no es lo que esperabas:

Revisa el template del prompt — ¿las instrucciones son claras?
Verifica que los tools y resources mencionados en el prompt existen
Prueba ejecutar los pasos del prompt manualmente (uno por uno) para ver dónde falla

"Error: MCP server task-manager timed out"

El server tarda demasiado en inicializar. Causas comunes:

La database es muy grande (millones de registros) — reduce el seed data
Un import tarda mucho — verifica que no estás importando paquetes pesados en el top level
Error en init_database() o seed_sample_data() — prueba en standalone primero

"Claude Code dice que no conoce ese tool/resource"

El server se conectó pero los registros fallaron. Verifica:

# Re-registrar
claude mcp remove task-manager
claude mcp add task-manager ...

# Verificar
claude
> /mcp

Si sigues sin ver los tools, el problema está en cómo registras tools en server.py. Compara con el código de la cápsula 03.

Tu server en el contexto del Claude Code Agentic Development Path

Este server no vive en un vacío. Es una pieza del path completo:

Guía	Cómo conecta con MCP
Guía 1: Intro to Claude Code	Aprendiste a usar Claude Code — ahora lo extendiste
Guía 2: Prompt Engineering	Las descriptions de tools son prompt engineering aplicado
Guía 3: Agentic Workflows	Tu server habilita flujos agénticos más poderosos
Guía 4: CLAUDE.md & Memory	Puedes documentar tu MCP server en CLAUDE.md para contexto persistente
Guía 5: MCP (esta)	Construiste la integración
Guía 6: Debugging & Code Review	Usarás tu conocimiento de tools para debuggear mejor
Guías 7-11	MCP servers como parte de tu toolkit profesional

Con cada guía que completes, tu MCP server se vuelve más útil. Y con cada MCP server que construyas, tu capacidad con Claude Code crece.

Cierre de la guía

Has completado los 8 módulos de Claude Code & MCP: Building Custom Integrations. Empezaste sin saber qué era MCP y terminaste con un server production-ready corriendo en Claude Code.

El path de Claude Code Agentic Development continúa con la Guía 6: Debugging & Code Review with Claude Code. Las habilidades que adquiriste aquí — entender cómo Claude Code se comunica con herramientas externas, cómo los tools procesan datos, cómo los errores se propagan — te dan una ventaja significativa para debuggear código generado por AI.

Tu MCP server no termina aquí. Agrégale tools cuando encuentres operaciones que repites. Mejora los prompts cuando descubras patrones de interacción. Compártelo si crees que otros pueden usarlo.

Construiste algo real. Eso es lo que importa.

Resumen

Configuraste tu MCP server en Claude Code y verificaste la conexión con /mcp
Ejecutaste 5 escenarios reales que demuestran el valor del server en workflows de desarrollo
Tu server pasa la rúbrica de 100 puntos: código funcional, tests, documentación y demo
Completaste el checklist final de calidad y funcionalidad
Identificaste áreas de mejora y extensiones futuras para tu server
Reflexionaste sobre todo lo aprendido en los 8 módulos de la guía
Tu MCP server es un proyecto de portfolio que demuestra dominio de MCP, Python, SQLite y testing

Recursos

MCP Specification — Especificación completa del protocolo
MCP Python SDK — SDK oficial Python
MCP TypeScript SDK — SDK oficial TypeScript
Awesome MCP Servers — Colección de MCP servers open source
Claude Code Documentation — Documentación oficial de Claude Code
Claude Code MCP Guide — Configuración de MCP en Claude Code
Model Context Protocol Blog — Anuncio original de MCP
MCP Inspector — Herramienta de debugging visual

← AnteriorTesting y Documentación