| name | bc-mcp-setup |
| description | Guide users through the complete Business Central MCP Server setup — from enabling the feature in BC to connecting it in Copilot Studio and pulling locally. |
BC MCP Server Setup (Guide)
This skill guides users through the end-to-end process of configuring the Business Central MCP Server and connecting it to a Copilot Studio agent. It does NOT write YAML directly — MCP connections must be created through the BC admin and Copilot Studio portals.
Why This Is a Guide, Not a Generator
The BC MCP connection requires:
- Feature enablement in Business Central's Feature Management
- MCP Server Configuration — created in the BC web client (page 8351)
- Connection reference — authenticated link created in Copilot Studio
- Once the connection is added via the UI and pulled locally, the action YAML can be edited with
/copilot-studio:configure-mcp-action
Reference
For detailed field-by-field reference, Dynamic Tool Mode comparison, tool naming conventions, and security recommendations, see:
Read: .github/skills/bc-mcp-setup/mcp-config-guide.md
Instructions
Phase 1 — Prerequisites Check
Before starting, verify the user has:
Verificación de requisitos previos:
| Requisito | Detalle |
|---|
| BC version | 27+ (2025 Wave 2 minimum — MCP requires this version) |
| Copilot Studio license | Con capacidad de Copilot Credits disponible |
| Permission set | MCP - ADMIN asignado al usuario en BC |
| Entorno | ¿Vas a configurar en sandbox o producción? |
¿Cumples con todos estos requisitos?
If the user is unsure about the BC version, guide them:
- BC admin center → Environments → check the version column
- Version 27.x = 2025 Wave 2, version 26.x = 2025 Wave 1 (NOT supported)
If the user doesn't have MCP-ADMIN:
- BC → Users → select the user → Permission Sets → add
MCP - ADMIN
Phase 2 — Enable MCP in Business Central
Walk the user through enabling the MCP feature:
Habilitar MCP Server en Business Central:
- Abre Business Central
- Busca y abre la página Feature Management (página 2610)
- O navega directamente:
https://businesscentral.dynamics.com/?page=2610
- Busca: "Feature: Enable MCP Server access"
- Cambia el estado a Enabled (for all users)
- Si se requiere, reinicia la sesión de BC
⚠️ Una vez habilitado, el MCP server proporciona acceso de solo lectura a todas las API pages expuestas por defecto. Para habilitar operaciones de escritura, necesitas crear una configuración específica (siguiente paso).
Phase 3 — Configure MCP Server in Business Central
Guide the user through creating an MCP Server configuration:
Crear configuración del MCP Server:
- Busca y abre "Model Context Protocol (MCP) Server Configurations" (página 8351)
- O navega:
https://businesscentral.dynamics.com/?page=8351
- Haz clic en New
- Configura los campos generales:
Present the general fields:
| Campo | Valor recomendado | Descripción |
|---|
| Name | Nombre descriptivo que coincida con el propósito del agente (e.g., CIRCE, COLLECTIONS-AGENT) | Este nombre aparece en Copilot Studio al asignar la configuración |
| Description | Breve descripción del propósito | e.g., "Agente de cobros y pagos" |
| Active | ✅ On | La configuración debe estar activa para que los agentes la usen |
| Dynamic Tool Mode | Ver recomendación abajo | Controla cómo se exponen las herramientas |
| Unblock Edit Tools | ✅ On (si necesitas escritura) | Habilita operaciones de creación, modificación y eliminación |
Dynamic Tool Mode Decision
Ask the user about their scenario:
¿Habilitar Dynamic Tool Mode?
| Dynamic Tool Mode ON | Dynamic Tool Mode OFF |
|---|
| Uso ideal | Prototipado, desarrollo, muchas APIs | Producción, control preciso |
| Cómo funciona | Las herramientas se descubren dinámicamente en runtime (bc_actions_search, bc_actions_describe, bc_actions_invoke) | Las herramientas se listan explícitamente en Copilot Studio |
| Límite de 70 tools | No aplica — discovery dinámico | Aplica — solo las primeras 70 herramientas están disponibles |
| Ventaja | Acceso a todas las APIs sin límite | Control granular, rendimiento predecible |
| Desventaja | Menos control, más tokens consumidos en discovery | Límite de 70 tools, configuración manual |
Recomendación para Circe: OFF en producción (control preciso de las APIs expuestas), ON durante prototipado.
Si activas Dynamic Tool Mode, el campo Discover Additional Objects permite dar acceso de lectura a API pages no incluidas explícitamente.
Add API Page Objects (Tools)
Based on the agent's purpose, recommend specific API pages:
Selección de API pages según el tipo de agente:
Collections / Finance agent (like Circe):
| API Page | Page ID | Allow Read | Allow Create | Allow Modify | Allow Delete |
|---|
| APIV2 - Customers | 30009 | ✅ | ❌ | ❌ | ❌ |
| APIV2 - Customer Ledger Entries | — | ✅ | ❌ | ❌ | ❌ |
| APIV2 - Sales Invoices | 30023 | ✅ | ❌ | ❌ | ❌ |
| APIV2 - Customer Payment Journals | 30028 | ✅ | ✅ | ✅ | ✅ |
| APIV2 - Aged Accounts Receivable | 30037 | ✅ | ❌ | ❌ | ❌ |
Sales agent:
| API Page | Allow Read | Allow Create | Allow Modify | Allow Delete |
|---|
| APIV2 - Customers | ✅ | ✅ | ✅ | ❌ |
| APIV2 - Items | ✅ | ❌ | ❌ | ❌ |
| APIV2 - Sales Orders | ✅ | ✅ | ✅ | ✅ |
| APIV2 - Sales Quotes | ✅ | ✅ | ✅ | ✅ |
| APIV2 - Sales Invoices | ✅ | ❌ | ❌ | ❌ |
Support agent:
| API Page | Allow Read | Allow Create | Allow Modify | Allow Delete |
|---|
| APIV2 - Customers | ✅ | ❌ | ❌ | ❌ |
| APIV2 - Sales Orders | ✅ | ❌ | ❌ | ❌ |
| APIV2 - Items | ✅ | ❌ | ❌ | ❌ |
| Custom incident/support APIs | ✅ | ✅ | ✅ | ❌ |
⚠️ Buena práctica de seguridad: NO uses "Add All Standard APIs" en producción. Crea API pages específicas para tu agente que limiten los campos expuestos. Principio de mínimo privilegio — expón solo lo que el agente necesita.
Ask the user which APIs to add:
¿Qué tipo de agente estás construyendo? Te recomendaré las API pages apropiadas. También puedes indicarme API pages personalizadas que hayas creado en tu extensión AL.
Phase 4 — Connect in Copilot Studio
Walk the user through the Copilot Studio connection:
Conectar el MCP Server en Copilot Studio:
- Abre Copilot Studio
- Navega a tu agente
- Ve a la pestaña Tools (Herramientas)
- Haz clic en + Add a tool
- Busca "Dynamics 365 Business Central MCP Server (Preview)"
- Si aparece "Not connected", haz clic y selecciona Create new connection
- Autentícate con tu cuenta de BC
- Selecciona Add and configure
- En la sección Inputs, configura:
| Campo | Valor |
|---|
| Environment | Selecciona tu entorno BC (e.g., SANDBOX_US, PRODUCTION) |
| Company | Selecciona la empresa (e.g., CRONUS USA, Inc.) |
| MCP Server Configuration | Nombre de la configuración creada en el paso anterior (e.g., CIRCE) — déjalo vacío para acceso de solo lectura a todas las APIs |
- Revisa la sección Tools para verificar las herramientas disponibles:
- Con Dynamic Tool Mode OFF: verás herramientas individuales como
ListAPIV2 - Customer_PAG30009
- Con Dynamic Tool Mode ON: verás
bc_actions_search, bc_actions_describe, bc_actions_invoke
- Haz clic en Save
Authentication Mode
Modo de autenticación:
| Modo | Cuándo usar |
|---|
| Invoker (delegado) | ✅ Recomendado para producción. Usa los permisos del usuario que interactúa con el agente |
| Maker (service-to-service) | Para agentes del sistema que operan sin contexto de usuario |
Recomendación: Usa Invoker para respetar los permisos de BC del usuario final.
Phase 5 — Validate
Guide the user through validation:
Validar la conexión:
- En Copilot Studio, haz clic en Test (esquina superior derecha)
- Escribe: "Muéstrame el cliente 10000" (o "Show me customer 10000")
- Verifica que:
- El agente invoca la herramienta MCP correcta
- Se devuelven datos del cliente
- Los campos visibles corresponden a la configuración de API pages
Pruebas adicionales sugeridas:
- "¿Cuántos clientes tengo?" (verifica acceso de lectura)
- "Muéstrame las facturas pendientes del cliente 10000" (verifica API de facturas)
- Si habilitaste escritura: "Crea un pago de 100€ para el cliente 10000" (verifica operaciones de escritura)
If validation fails, consult the troubleshooting table at the end of this skill.
Phase 6 — Pull to Local
After successful validation, pull the agent files locally:
Sincronizar archivos localmente:
- En VS Code, usa la extensión de Copilot Studio: Source Control → Pull
- Verifica que
connectionreferences.mcs.yml incluye la conexión BC MCP
- Verifica que existe un archivo de acción BC en
actions/:
Glob: **/actions/*BusinessCentral*.mcs.yml
- Si necesitas modificar la configuración del acción MCP, usa
/copilot-studio:configure-mcp-action
After the user confirms the pull:
- Read
connectionreferences.mcs.yml to verify the BC connection reference exists
- Read the BC action file to verify MCP structure (
InvokeExternalAgentTaskAction, operationId: InvokeMCP) and environment config (ManualTaskInput entries for bcenvironment, company, configurationName)
- Suggest updating
circe-memory.md with the MCP config details using /copilot-studio:update-memory
Troubleshooting
| Síntoma | Causa probable | Solución |
|---|
| BC no aparece en la búsqueda de herramientas MCP | Feature no habilitada o entorno incompatible | Verificar Feature Management → "Enable MCP Server access" está Enabled. Verificar BC version ≥ 27 |
| No hay herramientas disponibles después de conectar | Configuración MCP no activa o sin API pages | Abrir página 8351 en BC → verificar que Active está ON y que hay API pages añadidas |
| Error de autenticación al conectar | Credenciales inválidas o permisos insuficientes | Verificar que el usuario tiene MCP-ADMIN y licencia válida de BC |
| No se devuelven datos | Company o Environment incorrectos | Verificar que los valores de Environment y Company coinciden exactamente con BC admin center |
| Datos parciales o campos faltantes | API page no expone esos campos | Revisar la API page en BC — los campos deben estar definidos en el objeto de API. Crear API page personalizada si es necesario |
| Error "Company mismatch" | El nombre de empresa no coincide | Usar el nombre exacto de la empresa incluyendo mayúsculas y puntuación (e.g., "CRONUS USA, Inc." no "Cronus USA") |
| Operaciones de escritura fallan | Unblock Edit Tools desactivado | En BC página 8351 → activar Unblock Edit Tools y los permisos Allow Create/Modify/Delete en cada API page |
| Más de 70 APIs necesarias | Límite de herramientas de Copilot Studio | Activar Dynamic Tool Mode ON para discovery dinámico sin límite |
| Herramientas aparecen pero el agente no las usa | modelDescription insuficiente | Editar el modelDescription de la acción MCP con /copilot-studio:configure-mcp-action para incluir descripción detallada de las operaciones disponibles |
| El agente usa la API equivocada | Descripciones ambiguas entre APIs | Personalizar las API page descriptions en BC o editar modelDescription en la acción MCP |
After Completion
After the setup is complete:
-
Offer to configure the MCP action:
¿Quieres personalizar la configuración de la acción MCP? Puedo modificar el modelDescription, los inputs de entorno (bcenvironment, company, configurationName), o el modo de conexión con /copilot-studio:configure-mcp-action.
-
Offer to update agent instructions:
¿Quieres actualizar las instrucciones del agente para incluir guías sobre cómo usar las herramientas de BC? Puedo hacerlo con /copilot-studio:edit-agent.
-
Update memory:
Voy a actualizar circe-memory.md con los detalles de la configuración MCP.
References
