MCP_BusinessCentral - Servidor Model Context Protocol 🚀
Este proyecto implementa un servidor MCP para Microsoft Business Central, usando FastMCP y FastAPI, integrable con Claude Desktop y otros clientes AI.
🌐 Servidor Online Disponible
🎉 El servidor está desplegado y operativo en Azure App Service:
- URL: https://mcp-bc-javi-chb7bue4evbkeyb0.westeurope-01.azurewebsites.net
- Documentación API: https://mcp-bc-javi-chb7bue4evbkeyb0.westeurope-01.azurewebsites.net/docs
- Estado: ✅ 100% funcional con datos reales de Business Central
- Endpoints disponibles: GET /customers, /items, /orders, POST /customers
📋 Para usar el servidor desplegado: Consulta el archivo test-mcp-api.http con ejemplos de todas las operaciones.
📋 ¿Qué es MCP?
El Model Context Protocol (MCP) es un estándar abierto que permite a clientes AI acceder a herramientas, datos y servicios externos de forma segura y estructurada. MCP define una arquitectura cliente-servidor donde:
- MCP Host: Cliente AI (Claude, Copilot, etc.)
- MCP Client: Conector MCP en el host
- MCP Server: Este proyecto (Python) expone herramientas y lógica de negocio
- Transporte: JSON-RPC sobre stdin/stdout (local) o HTTP/SSE (remoto)
Más información: MCP servers en Microsoft Learn
🔒 Autenticación y Seguridad
- Se recomienda usar Microsoft Entra ID (Azure AD) y OAuth2 para entornos de producción.
- Consulta la guía de autenticación para Business Central.
Ejemplo: Autenticación OAuth2 con Entra ID
import httpx
def get_bc_token(tenant_id, client_id, client_secret, scope):
url = f"https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token"
data = {
"grant_type": "client_credentials",
"client_id": client_id,
"client_secret": client_secret,
"scope": scope
}
response = httpx.post(url, data=data)
response.raise_for_status()
return response.json()["access_token"]
Más información: Guía de autenticación
⚠️ Manejo de límites y errores
- Business Central impone límites de uso (rate limits) en sus APIs. Si recibes errores 429 (Too Many Requests) o 504 (Gateway Timeout), implementa lógica de reintentos y backoff.
- Más información: Límites de API en Business Central.
Ejemplo: Manejo de errores 429 y 504 en llamadas a la API
import httpx
import time
def call_bc_api_with_retry(url, headers, max_retries=5):
retries = 0
backoff = 2
while retries < max_retries:
response = httpx.get(url, headers=headers)
if response.status_code == 429:
wait = backoff ** retries
print(f"Rate limit alcanzado. Reintentando en {wait}s...")
time.sleep(wait)
retries += 1
elif response.status_code == 504:
print("Timeout de la API. Reintentando...")
time.sleep(backoff)
retries += 1
else:
return response
raise Exception("No se pudo completar la petición tras varios intentos")
Más información: Límites de API en Business Central
🏅 Buenas prácticas de integración
- Usa siempre los endpoints REST oficiales de Business Central para la integración.
- Desacopla la lógica de negocio del transporte MCP.
- Documenta claramente las herramientas expuestas y sus parámetros siguiendo el estándar MCP.
- Consulta la documentación de APIs REST de Business Central.
🏗️ Estructura del Proyecto
📁 MCP_BusinessCentral/
├── requirements.txt # Dependencias Python
├── README.md # Documentación principal
├── .env # Variables de entorno (no se incluye en repo)
├── .venv/ # Entorno virtual Python
├── .github/copilot-instructions.md
├── .vscode/tasks.json # Tareas de VS Code
├── task1.txt # (Ejemplo o pruebas)
└── 📁 bc_server/ # Paquete principal
├── BusinessCentralMCP.py # Servidor MCP (JSON-RPC) para BC
├── http_server.py # API REST (FastAPI) con OpenAPI/Swagger
├── setup_guide.py # Script de validación de entorno y credenciales
├── client.py # Cliente HTTP para la API de BC
├── config.py # Carga y validación de configuración
└── __init__.py
🎯 Servidores y APIs Implementados
1. BusinessCentralMCP.py - Servidor MCP (JSON-RPC)
Expone herramientas para interactuar con Business Central vía JSON-RPC:
- get_customers(limit): Lista clientes
- get_customer_details(customer_id): Detalle de un cliente
- get_items(limit): Lista artículos
- get_sales_orders(limit): Lista órdenes de venta
- create_customer(...): Crea un nuevo cliente
2. http_server.py - API REST (FastAPI)
Expone los mismos métodos anteriores vía HTTP REST, con documentación Swagger/OpenAPI.
3. setup_guide.py - Validación de entorno
Script para comprobar variables de entorno y conectividad con Azure AD y Business Central.
🛠️ Tecnologías Utilizadas
- FastMCP: Framework para servidores MCP (JSON-RPC)
- FastAPI: API REST moderna con documentación automática
- httpx: Cliente HTTP asíncrono
- Pydantic: Validación y serialización de datos
- python-dotenv: Gestión de variables de entorno
🚀 Instalación y Puesta en Marcha
💻 Entorno Local
1. Crear entorno virtual
python -m venv .venv
.venv\Scripts\Activate.ps1
2. Instalar dependencias
pip install -r requirements.txt
3. Validar entorno y credenciales
python bc_server/setup_guide.py
4. Lanzar el servidor MCP (JSON-RPC)
python -m bc_server.BusinessCentralMCP
5. Lanzar la API REST (FastAPI)
uvicorn bc_server.http_server:app --reload --host 0.0.0.0 --port 8000
Accede a la documentación interactiva en: http://localhost:8000/docs
☁️ Despliegue en Azure App Service
¿Quieres el servidor disponible online? Consulta la Guía Completa de Despliegue que incluye:
- Proceso paso a paso para Azure App Service
- Solución a todos los problemas encontrados
- Configuración de variables de entorno
- Scripts de automatización
- Suite de testing completa
Resultado: Servidor 100% operativo en Azure con integración real a Business Central.
🧪 Testing del Servidor Desplegado
El archivo test-mcp-api.http contiene una suite completa de tests para validar todas las funcionalidades:
### Health Check
GET https://mcp-bc-javi-chb7bue4evbkeyb0.westeurope-01.azurewebsites.net/health
### Listar Clientes
GET https://mcp-bc-javi-chb7bue4evbkeyb0.westeurope-01.azurewebsites.net/customers?limit=5
### Crear Cliente
POST https://mcp-bc-javi-chb7bue4evbkeyb0.westeurope-01.azurewebsites.net/customers
Content-Type: application/json
{
"displayName": "Cliente Test",
"email": "test@example.com"
}
Usar REST Client extension de VS Code para ejecutar los tests directamente desde el editor.
🔧 Integración con Claude Desktop
- Localiza el archivo de configuración de Claude Desktop:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
- Añade una entrada para el servidor MCP de Business Central, por ejemplo:
{ "mcpServers": { "businesscentral-mcp": { "command": "C:/ruta/completa/.venv/Scripts/python.exe", "args": ["-m", "bc_server.BusinessCentralMCP"] } } } - Reinicia Claude Desktop para que detecte el nuevo servidor MCP.
🛠️ Herramientas Disponibles (BusinessCentralMCP)
| Herramienta | Descripción | Parámetros principales |
|---|---|---|
| get_customers | Lista clientes de Business Central | limit (int) |
| get_customer_details | Detalle de un cliente por ID | customer_id (str) |
| get_items | Lista artículos | limit (int) |
| get_sales_orders | Lista órdenes de venta | limit (int) |
| create_customer | Crea un nuevo cliente | displayName, email, ... (ver código) |
Consulta la documentación Swagger en /docs si usas la API REST.
🧪 Testing y Desarrollo
- Claude Desktop: Configura el archivo de Claude Desktop y reinicia para probar las herramientas MCP.
- Modo desarrollo: Usa los scripts de la carpeta
bc_serverpara pruebas y debugging. - API REST: Ejecuta
uvicorn bc_server.http_server:app --reloady prueba los endpoints enhttp://localhost:8000/docs. - VS Code Task: Usa la tarea "Run Python Script" para lanzar scripts rápidamente.
🎯 Casos de Uso Demostrados
- Integración MCP con Business Central
- Exposición de datos de clientes, artículos y órdenes
- Creación de clientes desde herramientas AI
- API REST y JSON-RPC para integración flexible
📚 Referencias oficiales y recursos útiles
📖 Documentación del Proyecto
| Recurso | Descripción |
|---|---|
| Guía de Despliegue Azure | Proceso completo para llevar el servidor a producción |
| Suite de Tests | Validación completa de endpoints con REST Client |
| Configuración MCP | Servidor JSON-RPC para integración con AI clients |
| API REST | Endpoints HTTP con documentación OpenAPI |
🌐 Enlaces Oficiales de Microsoft
- MCP servers en Microsoft Learn
- APIs REST de Business Central
- Desarrollar apps conectadas a Business Central
- Límites de API en Business Central
- Documentación MCP Oficial
- FastMCP GitHub
- Claude Desktop
- Pydantic Docs
- Blog TechSphereDynamics
| Recurso | Enlace |
|---|---|
| MCP servers en Microsoft Learn | https://learn.microsoft.com/en-us/azure/api-management/export-rest-mcp-server#about-mcp-servers |
| APIs REST de Business Central | https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/webservices/api-overview |
| Autenticación y apps conectadas | https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-develop-connect-apps |
| Límites de API | https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/dynamics-rate-limits |
| Documentación MCP Oficial | https://modelcontextprotocol.io/llms-full.txt |
| FastMCP GitHub | https://github.com/jlowin/fastmcp |
| Claude Desktop | https://claude.ai/desktop |
| Pydantic Docs | https://docs.pydantic.dev/ |
| Blog TechSphereDynamics | https://techspheredynamics.com |
¡Desarrollado con visión y buen rollo! 😉
Para cualquier duda, revisa los comentarios en el código o consulta la documentación oficial de MCP.