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
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_server para pruebas y debugging.
API REST: Ejecuta uvicorn bc_server.http_server:app --reload y prueba los endpoints en http://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

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.

Business Central MCP Server