pbi-mcp-remote

Servidor MCP (Model Context Protocol) remoto y centralizado, en Node.js, que expone herramientas para que modelos de IA interactúen con Microsoft Fabric (workspaces e items: Lakehouse, Warehouse, Notebook, DataPipeline, SemanticModel, Report, etc.) a través de la Fabric Core REST API.

Autenticación: OAuth 2.1 delegado con Microsoft Entra ID. Cada usuario final se loguea con su propia cuenta; el servidor usa el token delegado de ese usuario para llamar a Fabric, por lo que hereda exactamente los permisos y restricciones que ya tiene configurados en Fabric (RBAC de workspace, sensitivity labels, etc.). No se usa ninguna identidad de aplicación compartida para acceder a datos de Fabric.

Alcance actual: Fabric Core REST API (workspaces e items) y Power BI REST API clásica (datasets, reports, dashboards, gateways). Fuera de alcance por ahora: SQL endpoints de Lakehouse/Warehouse, orquestación de jobs/pipelines.

Fabric y Power BI son audiencias distintas de Entra ID (api.fabric.microsoft.com vs analysis.windows.net/powerbi/api), así que el servidor mantiene un access token cacheado por recurso, ambos derivados del mismo refresh token de la sesión del usuario — ver "Arquitectura" para el detalle.

Arquitectura

El servidor actúa simultáneamente como:

• Authorization Server de cara a los clientes MCP (Claude, MCP Inspector, etc.): expone /.well-known/oauth-authorization-server, /authorize, /token, /register.
• Proxy hacia Entra ID: es el único componente que habla directamente con Entra (App Registration fijo, confidential client). El cliente MCP nunca ve el token real de Entra — solo un JWT propio de corta vida emitido por este servidor, que internamente resuelve a una sesión con los tokens delegados de Entra (access + refresh), guardados cifrados server-side.

Flujo: cliente MCP → /authorize → redirect a Entra (PKCE propio del servidor) → login/consentimiento del usuario → /callback → intercambio de código vía MSAL → sesión guardada → el servidor completa el /authorize original y emite su propio código → el cliente pide /token y recibe un JWT propio → cada llamada a /mcp resuelve la sesión y, si el token del recurso correspondiente (Fabric o Power BI) está por vencer, lo refresca de forma transparente antes de llamar a la API real con el token delegado del usuario.

Un access token solo tiene una audiencia, así que un mismo token no sirve para Fabric y Power BI a la vez. En el login inicial se piden los scopes combinados de ambos recursos (una sola pantalla de consentimiento), y luego el servidor deriva un access token por recurso a partir del refresh token compartido (acquireTokenByRefreshToken con los scopes de cada uno), cacheando cada uno con su propio vencimiento.

Configuración de Entra ID (paso a paso)

1. Azure Portal → Microsoft Entra ID → App registrations → New registration.
   • Nombre: p. ej. pbi-mcp-remote.
   • Supported account types: Single tenant (recomendado para esta fase).
   • Redirect URI: tipo Web, http://localhost:3000/callback (agregar la URL de producción cuando se decida el hosting).
2. Certificates & secrets → New client secret. Copiar el value (no el secret ID) apenas se genera.
3. API permissions → Add a permission → APIs my organization uses → Power BI Service (este mismo recurso expone tanto los scopes de Fabric como los de Power BI clásica). Elegir Delegated permissions (nunca Application permissions):
   • Workspace.ReadWrite.All, Item.ReadWrite.All (Fabric)
   • Dataset.Read.All, Dataset.ReadWrite.All (necesario para powerbi_trigger_dataset_refresh), Report.Read.All, Dashboard.Read.All, Gateway.Read.All (Power BI clásica)
   • openid, profile, offline_access (necesarios para el refresh token).
4. Si tu tenant lo requiere, pedile a un admin que haga Grant admin consent.
5. Copiar Directory (tenant) ID, Application (client) ID y el client secret al .env (ver abajo).
6. No hace falta una segunda app ni un segundo redirect URI para Power BI — es el mismo App Registration, solo se amplía la lista de scopes pedidos (FABRIC_SCOPES + POWERBI_SCOPES en .env). Si ya tenías sesiones activas creadas antes de agregar Power BI, hace falta desconectar/reconectar una vez desde el cliente MCP para que corra el flujo de consentimiento combinado.

Configuración local

cp .env.example .env
# completar ENTRA_TENANT_ID, ENTRA_CLIENT_ID, ENTRA_CLIENT_SECRET,
# MCP_JWT_SIGNING_SECRET y SESSION_ENCRYPTION_KEY con valores propios (no los de ejemplo)

npm install
npm run dev

El servidor queda escuchando en http://localhost:3000. El endpoint MCP remoto es http://localhost:3000/mcp.

Probar end-to-end

npx @modelcontextprotocol/inspector

Apuntar el Inspector a http://localhost:3000/mcp. Al conectar, dispara el flujo OAuth completo: redirige a Entra ID, el usuario se loguea y consiente los scopes de Fabric y Power BI juntos, vuelve al Inspector ya autenticado, y desde ahí se pueden listar/invocar las herramientas (fabric_list_workspaces, powerbi_list_datasets, etc.) contra el tenant real, respetando los permisos del usuario logueado.

Docker

docker compose up --build

Levanta el servidor + Redis como session store (recomendado para más de una instancia). Para una sola instancia en desarrollo, SESSION_STORE=memory (default del .env.example) alcanza.

Herramientas MCP disponibles

Fabric Core REST API:

• fabric_list_workspaces, fabric_get_workspace, fabric_create_workspace, fabric_update_workspace, fabric_delete_workspace
• fabric_list_workspace_role_assignments
• fabric_list_items, fabric_get_item, fabric_create_item, fabric_update_item, fabric_delete_item
• fabric_list_item_connections
• fabric_list_supported_item_types

Power BI REST API clásica:

• powerbi_list_datasets, powerbi_get_dataset, powerbi_list_dataset_datasources, powerbi_get_dataset_refresh_history, powerbi_trigger_dataset_refresh
• powerbi_list_reports, powerbi_get_report, powerbi_list_report_datasources
• powerbi_list_dashboards, powerbi_get_dashboard
• powerbi_list_gateways, powerbi_list_gateway_datasources