mcp-server-demo
Servidor MCP (Model Context Protocol) que expone herramientas propias para que un LLM las use de forma estandarizada: consultas a una base de datos y a una API externa, con validación de entrada y manejo de errores.
Objetivo
Demostrar dominio del protocolo abierto que está estandarizando cómo los LLM acceden a herramientas y datos externos. En vez de acoplar tools a un framework concreto, se construye un servidor MCP reutilizable por cualquier cliente compatible (Claude Desktop, el sistema multi-agente de este portfolio, IDEs, etc.).
El servidor expone, como mínimo:
- Tools — acciones invocables: consultar una base de datos local (SQLite) y llamar a una API externa (ej. clima, tipo de cambio, o una API pública de datos).
- Resources — datos legibles por el modelo (ej. el esquema de la base, un catálogo).
- (Opcional) Prompts — plantillas de prompt reutilizables parametrizadas.
Stack tecnológico sugerido
- Opción A — Python: SDK oficial
mcp(conFastMCP) — recomendado por rapidez de desarrollo - Opción B — TypeScript:
@modelcontextprotocol/sdk— útil si se quiere mostrar versatilidad - Transporte:
stdiopara uso local con clientes de escritorio; Streamable HTTP para exposición remota - Base de datos: SQLite (con un dataset de ejemplo sembrado)
- API externa: una API pública sin fricción (ej. Open-Meteo para clima, o exchangerate.host)
- Validación: Pydantic (Python) o Zod (TS)
- Cliente de prueba: MCP Inspector (
npx @modelcontextprotocol/inspector) y/o Claude Desktop - Testing / calidad: pytest (o vitest), ruff/black (o eslint/prettier)
Estructura de carpetas propuesta (variante Python)
mcp-server-demo/
├── README.md
├── pyproject.toml
├── .env.example
├── data/
│ ├── seed.sql # Esquema + datos de ejemplo
│ └── demo.db # SQLite generada (git-ignored)
├── src/
│ ├── server.py # Entry point: instancia FastMCP y registra todo
│ ├── config.py
│ ├── tools/
│ │ ├── db_tools.py # query_customers, get_order_by_id, etc.
│ │ └── api_tools.py # get_weather, get_exchange_rate, etc.
│ ├── resources/
│ │ └── schema.py # Expone el esquema de la DB como resource
│ └── db/
│ └── connection.py # Conexión y helpers (queries parametrizadas)
├── scripts/
│ └── seed_db.py # Crea demo.db desde seed.sql
├── examples/
│ └── claude_desktop_config.json # Config de ejemplo para registrar el server
└── tests/
├── test_db_tools.py
└── test_api_tools.py
Checklist de implementación
Fase 1 — Setup
- Inicializar el proyecto y elegir SDK (Python
mcp/FastMCPo TypeScript). - Definir
.env.example(base URL de la API externa, API key si aplica). - Crear
seed.sqlcon un dominio simple (ej. clientes/pedidos) y el scriptseed_db.py.
Fase 2 — Tools de base de datos
- Implementar la conexión con queries parametrizadas (evitar inyección SQL).
- Exponer al menos 2 tools de DB (ej.
search_customers,get_order_by_id) con schema de entrada tipado y descripciones claras. - Manejar el caso "sin resultados" y errores de forma explícita (mensajes útiles para el LLM).
Fase 3 — Tools de API externa
- Implementar un cliente HTTP con timeout y reintentos.
- Exponer al menos 1 tool que llame a la API externa (ej.
get_weather(city)). - Normalizar la respuesta a un formato compacto y útil para el modelo.
Fase 4 — Resources y prompts
- Exponer el esquema de la DB como resource para que el modelo sepa qué puede consultar.
- (Opcional) Añadir un prompt template reutilizable (ej. "analiza estos pedidos").
Fase 5 — Robustez y seguridad
- Validar todas las entradas antes de tocar DB o API.
- Descripciones de tools precisas (el LLM decide cuándo usarlas según la descripción).
- No exponer secretos en respuestas ni logs; leer keys desde entorno.
- Logging básico de invocaciones (tool, args, latencia).
Fase 6 — Integración y prueba
- Probar con MCP Inspector: listar tools/resources e invocarlos.
- Registrar el server en Claude Desktop con
examples/claude_desktop_config.jsony hacer una prueba real. - (Opcional) Consumirlo desde
multi-agent-orchestrationpara cerrar el portfolio. - Variante Streamable HTTP para demostrar exposición remota.
Fase 7 — Documentación
- README con cómo levantar el server (stdio y HTTP) y cómo registrarlo en un cliente.
- Tabla de tools/resources con descripción, parámetros y ejemplo.
- ADR breve: elección de transporte (stdio vs HTTP) y del SDK.
Criterios de "terminado"
Un cliente MCP (Inspector o Claude Desktop) descubre las herramientas, un LLM las invoca correctamente contra la DB y la API externa, y las entradas están validadas y los errores manejados. El server funciona por stdio local y, opcionalmente, por HTTP remoto.