Skip to main content
Glama
Demo MCP Server

Demo MCP Server

by yonerloyinza

Demo MCP Server — MCP 2026-07-28 (Stateless Core)

Servidor MCP (Model Context Protocol) bajo la especificación 2026-07-28 con arquitectura Stateless Core (sin estado).

📋 Resumen de especificaciones aplicadas

Esta implementación sigue el estándar MCP 2026-07-28 gobernado por la Agentic AI Foundation (Linux Foundation), soportado nativamente por AWS, Cloudflare, Google y OpenAI.

Característica

Estado en este proyecto

Stateless Core

✅ Implementado — cero persistencia de sesión en memoria

Streamable HTTP

✅ Transporte único (HTTP+SSE removido)

Cabeceras obligatorias SEP-2243

✅ Mcp-Protocol-Version, Mcp-Method, Mcp-Name

Estado via tokens

✅ token_transaccion viaja en argumentos y respuestas

Blobs binarios (Base64)

✅ type: "blob" con mimeType para imágenes/PDFs

Cache-Control

✅ public para catálogos, no-store para datos sensibles

Roots

❌ No implementado (deprecado)

Sampling

❌ No implementado (deprecado)

Logging (setLevel/message)

❌ Removido (deprecado)

Related MCP server: MCP Calculator Streamable HTTP

🏗️ Arquitectura

Cliente MCP (Kilo, VS Code, Inspector, Orquestador IA)
        │
        │ HTTP POST /mcp  (cabeceras Mcp-*)
        │
┌─────► demo://welcome          [recurso estático]
│  ├─► demo://greeting/{name}   [recurso plantilla]
│  ├─► demo://adjunto/{id}      [recurso blob imagen]
│  ├─► add(a, b)                [herramienta]
│  ├─► obtener_factura(id)      [herramienta + token estado]
│  ├─► aplicar_descuento(tok)   [herramienta + valida token]
│  ├─► guardar_evidencia_multimedia(blob) [herramienta + imagen Base64]
│  ├─► draft_greeting()         [prompt]
│  └─► complete()               [autocompletado]

Punto clave: el servidor no guarda sesiones en memoria. Si un balanceador de carga redirige una petición a otro contenedor, el token_transaccion viaja de vuelta en cada llamada y valida el estado.

📦 Archivos del proyecto

Archivo

Propósito

server.py

Servidor MCP principal (Streamable HTTP) con todas las capacidades

server_fastapi.py

Servidor sobre FastAPI con cabeceras obligatorias SEP-2243

server_multimedia.py

Ejemplo dedicado a imágenes y blobs Base64

server_db.py

Ejemplo con SQLite (base de datos stateless + tokens)

test_client.py

Tests end-to-end contra http://127.0.0.1:8001/mcp

requirements.txt

Dependencias

.env.example

Template de variables de entorno

.vscode/mcp.json

Configuración MCP para VS Code

.kilo/kilo.jsonc

Configuración MCP para Kilo CLI

LICENSE

MIT

⚙️ Instalación

# Clonar
git clone https://github.com/yonerloyinza/mi-mcp.git
cd mi-mcp

# Entorno virtual
python -m venv .venv
source .venv/bin/activate          # Linux/macOS
# .venv\Scripts\activate           # Windows

# Dependencias
pip install -r requirements.txt

# Configurar entorno
cp .env.example .env
# Editar .env (ajustar PORT, HOST, LOG_LEVEL, AUTH_REQUIRED, MCP_TOKEN)

🌐 Variables de entorno

Variable

Default

Uso

HOST

127.0.0.1

Dirección de escucha (bind) del servidor

PORT

8001

Puerto HTTP del servidor MCP

LOG_LEVEL

INFO

Nivel de logging (DEBUG, INFO, WARNING, ERROR, CRITICAL)

AUTH_REQUIRED

false

Activa/desactiva autenticación Bearer en HTTP

MCP_TOKEN

(requerido si AUTH_REQUIRED=true)

Token Bearer para proteger solicitudes HTTP

DB_PATH

./mcp_demo.db

Ruta al archivo SQLite (server_db.py)

Nota: AUTH_REQUIRED=true obliga a enviar Authorization: Bearer <MCP_TOKEN> en cada petición HTTP. No se aplica a STDIO.

🚀 Uso rápido

Servidor principal (server.py)

# Terminal 1 — iniciar servidor
.venv/bin/python server.py

# Terminal 2 — ejecutar tests
.venv/bin/python test_client.py

Servidor FastAPI (server_fastapi.py)

.venv/bin/python server_fastapi.py
# Endpoint: POST http://127.0.0.1:8002/mcp
# Cabeceras obligatorias:
#   Mcp-Protocol-Version: 2026-07-28
#   Mcp-Method: tools/call
#   Mcp-Name: add
#   Authorization: Bearer <MCP_TOKEN>  (si AUTH_REQUIRED=true)

Servidor multimedia (server_multimedia.py)

.venv/bin/python server_multimedia.py
# Puerto 8003 — manejo de imágenes y documentos como blobs Base64

Servidor de base de datos (server_db.py)

.venv/bin/python server_db.py
# Puerto 8004 — SQLite con facturas y adjuntos BLOB

🛠️ Ejemplos de uso

1. Suma de dos números (herramienta)

POST /mcp HTTP/1.1
Mcp-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: add
Content-Type: application/json

{"arguments": {"a": 15, "b": 27}}

Respuesta: {"result": 42}

2. Flujo de factura con token (estado sin sesión)

# Paso 1: obtener factura + token
POST /mcp ... Mcp-Name: obtener_factura
{"arguments": {"id_factura": "FAC-2026-001"}}

# Respuesta incluye: "token_transaccion": "abc123..."

# Paso 2: aplicar descuento con el token
POST /mcp ... Mcp-Name: aplicar_descuento
{"arguments": {"id_factura": "FAC-2026-001", "porcentaje": 15, "token_transaccion": "abc123..."}}

3. Subir imagen (Base64 blob)

POST /mcp ... Mcp-Name: guardar_evidencia_multimedia
{"arguments": {
  "id_paciente": "PAC-9948",
  "descripcion": "Radiografía de tórax",
  "mime_type": "image/png",
  "archivo_base64": "iVBORw0KGgoAAAANSUhEUgAA..."
}}

4. Autocompletado (completion/complete)

POST /mcp ... Mcp-Method: completion/complete
{"ref": {"type": "ref/prompt", "name": "draft_greeting"}, "argument": {"name": "style", "value": "f"}}

Respuesta: {"values": [{"value": "friendly", "label": "friendly"}, ...], "hasMore": false}

🧪 Testing

.venv/bin/python test_client.py

Valida: inicialización, tools, resources, prompts, completions.

Nota: Los tests no incluyen validación de capacidades deprecadas (Roots, Sampling, Logging/setLevel).

📚 Características MCP obsoletas (no implementadas)

Característica

Estado

Por qué

HTTP + SSE

Deprecado

Reemplazado por Streamable HTTP (más directo, seguro, escalable)

Roots (roots/list, notifications/roots/list_changed)

Deprecado

Complejidad innecesaria, sin control de acceso estricto

Sampling (sampling/createMessage)

Deprecado

Mezcla inferencia del modelo dentro del protocolo

Logging (logging/setLevel, notifications/message)

Deprecado

El logging debe gestionarse con sistemas de observabilidad estándar (OpenTelemetry, stdout/stderr)

Este servidor usa exclusivamente Streamable HTTP como transporte y no implementa Roots, Sampling ni Logging a nivel de protocolo.

🔌 Integración con clientes MCP

VS Code

El archivo .vscode/mcp.json registra el servidor. Si usas la extensión Kilo Code, configura la cabecera Authorization: Bearer <MCP_TOKEN> solo cuando la autenticación esté habilitada.

Kilo CLI

El archivo .kilo/kilo.jsonc configura el MCP. En la TUI, usa /mcps para activar/desactivar.

MCP Inspector

# Modo CLI (directo)
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8001/mcp --method tools/list

# Modo interactivo (navegador)
npx @modelcontextprotocol/inspector
# Luego conectar a: http://127.0.0.1:8001/mcp

🔐 Seguridad

  • Autenticación Bearer: AUTH_REQUIRED=true + MCP_TOKEN en .env.

  • Cache-Control: no-store en respuestas de herramientas (datos sensibles no cachean en proxies).

  • Cache-Control: public, max-age=300 en catálogos de herramientas (permitido cachear).

  • Cache-Control: private en datos de pacientes/adjuntos (no cachear en CDNs públicos).

  • HTTPS: Si expones el servidor a otra máquina, usa HTTPS/TLS delante (proxy inverso).

📄 Licencia

MIT — ver archivo LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      A demonstration MCP server built with FastMCP v2.0 that provides basic mathematical calculations and greeting functionality. Features Docker containerization, comprehensive testing, and CI/CD automation for learning MCP development patterns.
      2
      -
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides basic arithmetic calculation tools through an HTTP-accessible MCP server. Supports mathematical operations like addition with streamable responses for integration with MCP clients.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A basic MCP server example that provides simple arithmetic tools (addition and subtraction) and personalized greeting resources. Serves as a foundation for learning MCP server implementation and development.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A foundational Model Context Protocol server demonstrating core functionality through basic arithmetic tools and personalized greeting resources. It serves as a template for developers learning to build and deploy MCP-enabled AI applications.
      GPL 3.0