empresa-mcp-demo

Servidor MCP remoto de demostración para validar la arquitectura Claude Team + MCP custom sin construir interfaz propia.

Desarrollado por Cyanea Tech Partner como prueba de viabilidad de la Opción 1: el cliente usa claude.ai para interactuar con sus propios sistemas (ERP, BD, APIs) a través de MCP servers desplegados en la nube por Cyanea.

---

Qué hace este servidor

Expone 5 tools a Claude a través del protocolo MCP (Streamable HTTP):

Tool	Descripción
consultar_pedidos(estado?)	Pedidos con nombre de cliente y producto. Filtra por pendiente, en camino o entregado. Sin filtro devuelve todos.
listar_clientes()	Todos los clientes con empresa, email y ciudad.
listar_productos()	Todos los productos con categoría, precio EUR y stock.
resumen_negocio()	KPIs: total pedidos, desglose por estado, productos con stock < 10.
tipo_de_cambio(moneda)	Tipo de cambio EUR → divisa en tiempo real (USD, GBP, JPY, MXN, COP…). Fuente: api.frankfurter.app, sin API key.

La base de datos (empresa_prueba.db) es una BD SQLite con datos ficticios de clientes, productos y pedidos de una empresa española. Se recrea automáticamente al arrancar el servidor mediante setup_db.py.

---

Arquitectura

Empleado del cliente
        ↓
   claude.ai Team (navegador)
        ↓
   Conector custom registrado por el Owner de la organización
        ↓
   Este servidor desplegado en Render.com
        ↓                          ↓
  empresa_prueba.db         api.frankfurter.app
  (SQLite local)            (divisas, tiempo real)

El empleado hace preguntas en lenguaje natural. Claude llama a las tools del MCP, consulta los datos reales y responde de forma interpretada. El usuario nunca ve SQL ni JSON.

---

Stack técnico

• Python 3.12 (runtime.txt para Render; funciona en 3.10+)
• FastMCP 3.x — framework para construir MCP servers con decoradores
• httpx — cliente HTTP async para llamadas a la API de divisas
• SQLite — BD embebida, sin servidor externo
• Render.com — hosting free tier para el deploy

---

Configuración local

1. Clonar y crear entorno virtual

git clone https://github.com/TU_USUARIO/empresa-mcp-demo.git
cd empresa-mcp-demo
python -m venv .venv

Activar el entorno:

• Windows: .venv\Scripts\activate
• Mac/Linux: source .venv/bin/activate

2. Instalar dependencias

pip install -r requirements.txt

3. Crear la base de datos

python setup_db.py

Genera empresa_prueba.db con 5 clientes, 5 productos y 10 pedidos de ejemplo. Si ya existe, la borra y la recrea (idempotente).

4. Arrancar el servidor

python server.py

El servidor queda disponible en http://localhost:8000/mcp.

5. Verificar que funciona (opcional)

Prueba rápida con curl:

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Debe devolver las 5 tools en la respuesta.

---

Deploy en Render.com

Requisitos previos

• Cuenta en render.com (free tier suficiente)
• Este repo subido a GitHub

Pasos

1. En el dashboard de Render: New → Web Service
2. Conectar el repo de GitHub empresa-mcp-demo
3. Configurar el servicio:

Campo	Valor
Language / Environment	Python
Branch	main
Build Command	pip install -r requirements.txt
Start Command	python setup_db.py && python server.py
Instance Type	Free

4. Hacer clic en Deploy. El primer deploy tarda ~2-3 minutos.
5. La URL del servidor queda en: https://[nombre-app].onrender.com/mcp

Importante: El Start Command incluye setup_db.py antes del servidor porque el sistema de archivos de Render es efímero — la BD se pierde en cada reinicio y hay que recrearla. No elimines esa parte del comando.

Cold start (free tier)

Render free apaga el servicio tras 15 minutos de inactividad. La primera petición después tarda ~30 segundos mientras el servidor arranca. Para una demo, abre la URL del servicio en el navegador unos minutos antes para despertarlo.

Si necesitas que esté siempre activo, el plan Starter de Render cuesta ~$7/mes y elimina el cold start.

---

Conectar a claude.ai Team

Solo puede hacerlo el Owner de la organización en claude.ai.

1. Ir a claude.ai/admin-settings/connectors
2. Clic en Add custom connector
3. Pegar la URL: https://[nombre-app].onrender.com/mcp
4. Guardar — claude.ai verifica la conexión automáticamente

Una vez registrado, cada miembro del Team puede activarlo en sus conversaciones desde el botón "+" en el chat → Connectors.

---

Preguntas de demo para claude.ai

Una vez conectado el conector, prueba estas preguntas:

¿Qué pedidos están pendientes?
Dame un resumen del estado del negocio hoy
¿Qué productos tienen poco stock?
¿Cuánto vale el euro en dólares ahora mismo?
¿Cuánto sumarían en libras esterlinas los pedidos pendientes?
¿Qué clientes tienen pedidos en camino?

La última pregunta combina datos de la BD con la API de divisas en una sola respuesta.

---

Archivos del proyecto

├── server.py        # MCP server principal (5 tools)
├── setup_db.py      # Crea y puebla empresa_prueba.db
├── requirements.txt # Dependencias Python
├── runtime.txt      # Versión de Python para Render
└── .gitignore       # Excluye .db, .venv, __pycache__, etc.

La BD (empresa_prueba.db) no está en el repo — se genera en local y en Render al arrancar.

---

Notas para producción real

Este servidor es una demo con datos ficticios. Para un cliente real:

• Reemplazar las queries SQLite por llamadas a la API del ERP del cliente (REST, GraphQL, etc.)
• Añadir autenticación OAuth al MCP server (claude.ai lo soporta vía Advanced Settings en el conector)
• Migrar a Render Starter (~$7/mes) o VPS propio para eliminar cold start
• Si los datos son sensibles y no pueden salir de la red del cliente, desplegar el servidor dentro de su infraestructura (VPN o servidor interno accesible por Anthropic)