Blog

Automating Business Central Word Report Layouts with MCP: Hands-On Guide to BC Word Layout MCP 2.1.0, Claude Code & BC 29 Themes

Senior Microsoft Dynamics 365 Business Central developer and solutions architect using Claude Code with Model Context Protocol to automate Word report layouts

Architectural Strategic Overview

Report design has long been one of the most frustrating bottlenecks in Microsoft Dynamics 365 Business Central development. While Word report layouts (.docx) offer business users layout familiarity over heavy RDLC datasets, modifying custom XML parts manually is notoriously brittle: a single misplaced element, broken namespace, or corrupted repeating row content control can prevent the layout from opening or printing. The release of the open-source BC Word Layout Local MCP v2.1.0 marks a turning point in agentic ERP development. By leveraging Anthropic’s Model Context Protocol (MCP), developers can now empower AI agents like Claude Code and GitHub Copilot to create, modify, validate, and preview Business Central Word layouts through typed, schema-safe toolsโ€”with full support for the upcoming BC 29 Report Themes engine.


Key Technical Takeaways for BC Architects & Developers

  • Eliminating XML Corruption: Instead of allowing LLMs or developers to directly slice and dice raw OpenXML tags inside a .docx zip archive, the MCP server enforces typed tools that guarantee structural integrity.
  • BC 29 Theme Engine Support: Full compatibility with BC 29 dynamic report themesโ€”enabling native Word theme colors, paragraph styles, and colored table borders.
  • The New set_layout_theme Tool: Allows AI agents to dynamically set or modify a report layout’s own palette, typography, and accent tints on demand.
  • Conditional Page Logic: Built-in controls for rendering text blocks that print exclusively on the first page, on every page except the last, or strictly on the final page (ideal for remittance slips and signature blocks).
  • Vertically Merged Cells: Supports multi-row vertical cell merging in tables, aligning with Microsoft’s new BC 29 header and footer layout specifications.
  • Target Safety via app.json: The MCP server inspects the extension’s app.json and refuses BC 29-only features if the project targets older versions (BC 28, 27, or earlier).

1. The Core Problem: Why Business Central Word Layouts Corrupt

Microsoft Dynamics 365 Business Central offers multiple report layout engines: RDLC (SQL Server Reporting Services), Excel layouts, and Word layouts. For customer-facing transactional documentsโ€”such as Sales Invoices, Purchase Orders, Order Confirmations, and Customer Statementsโ€”Word layouts (.docx) are frequently favored by functional consultants and end users because Microsoft Word offers intuitive desktop styling.

However, under the hood, Business Central integrates with Word documents through Custom XML Parts. The report dataset defined in the AL report object (dataset { dataitem(...) { column(...) } }) is injected into the Word document package as an XML schema. Content Controls within the Word document map to specific XPath nodes in this XML data stream.

Pain Point Traditional Manual Workflow The Consequence
XML Schema Desynchronization Developers update AL report columns, then must manually export the layout, open Word Developer tools, and re-map XML parts. Orphaned content controls cause silent rendering failures or blank print outputs.
Repeating Table Row Corruption Nesting repeating content controls across line items and multi-line descriptions inside table rows. Word’s OpenXML engine easily corrupts table definitions, causing Word to throw “Unreadable Content” errors.
Direct AI LLM Hallucinations Prompting standard ChatGPT or Claude models to generate or edit raw document.xml files. LLMs struggle with complex OpenXML relationship IDs and namespace prefixes, corrupting the document container.

2. How Model Context Protocol (MCP) Solves Layout Automation

The Model Context Protocol (MCP), introduced by Anthropic, provides an open, standardized protocol that allows AI models to safely execute tools and interact with local environments.

Rather than feeding an entire 20,000-line document.xml file to an AI model and hoping it doesn’t break an XML tag, the BC Word Layout Local MCP server acts as a robust abstraction barrier:

The Typed Tool Paradigm

Instead of editing raw text, AI agents (such as Claude Code in the CLI or GitHub Copilot in VS Code) communicate with the MCP server using strongly typed JSON-RPC tools. The agent issues high-level intentsโ€”such as “apply corporate theme palette”, “bind line item table to Line dataitem”, or “set remittance section to print only on the last page”. The MCP server validates the OpenXML schema, applies the change deterministically, and verifies document integrity before returning the result.

Terminal running Model Context Protocol MCP tools validating Business Central Word report layout OpenXML schema

3. Whatโ€™s New in BC Word Layout MCP 2.1.0: BC 29 & Themes

The v2.1.0 release represents a major leap forward, focusing specifically on Microsoft Business Central 29 capabilities and report theming:

Feature 01

Native BC 29 Report Themes

Full support for theme colors, colored table borders, and paragraph styles formatted exactly as Microsoft Word and Business Central expect. Report elements can now inherit dynamic tints and font styles directly from the active BC report theme.

Feature 02

The set_layout_theme Tool

A dedicated tool allowing AI agents to inspect, set, or restyle a layout’s built-in color scheme and font pairs. Agents can re-theme an entire suite of documents to match brand guidelines with a single prompt.

Feature 03

Conditional Page Printing Logic

Solves a long-standing developer struggle: configuring text and sections that print only on the last page, on every page except the last, or only on the first page without complex custom VBA or Word field coding.

Feature 04

Vertically Merged Table Cells

Support for vertical cell merging in tables (w:vMerge), matching Microsoft’s updated BC 29 multi-level header and footer layout structures for complex invoices and multi-currency ledgers.

Built-in Target Version Enforcement via app.json

Crucially for enterprise engineering safety, the MCP server automatically inspects your active AL project’s app.json file. If your target platform is set to an older version (e.g., BC 28, BC 27, or earlier), the server strictly refuses to inject BC 29-only features. This prevents AI agents from accidentally introducing breaking changes or incompatible XML schemas into production enterprise extensions.

4. Architectural Rules: Theme Colors vs. Fixed Brand Colors

Before the v2.1.0 release, the author verified the implementation by printing an entire test pack of 32 report layouts in a live BC 29 sandbox. The testing established a fundamental architectural rule for report designers and AI prompts:

Color Type Behavior in BC 29 Runtime Recommended Architectural Use Case
Theme Colors & Tints Dynamically inherit colors, tints, and font pairings from whichever Report Theme is active on the Business Central tenant or company. Multi-company environments, white-label partner templates, or organizations that allow subsidiary-level color themes.
Fixed Colors & Named Fonts Remain completely static regardless of tenant report theme selections; hardcoded HEX/RGB values and explicit font names are preserved. Strict corporate identity rules: corporate logos, regulated legal notices, and brand-mandated header banners that must never change.

5. Hands-On Setup: Claude Code, VS Code & NuGet

Setting up the MCP server in your local development environment takes less than two minutes. The tool is distributed via NuGet and can be run directly using dnx or configured inside your AI agent settings:

Option A: Configuring in Claude Code (CLI)

To install the MCP server as a plugin for Claude Code, add it to your project or user MCP configuration:

{
  "mcpServers": {
    "bc-word-layout": {
      "command": "dnx",
      "args": ["run", "--package", "BCWordLayout.Mcp", "--version", "2.1.0", "--", "serve"]
    }
  }
}

Option B: Running Directly with .NET Tool (dnx)

You can also execute the server directly without pre-installing packages using the .NET tool runner:

# Run the BC Word Layout MCP server directly from NuGet
dnx run --package BCWordLayout.Mcp --version 2.1.0

6. Practical Agentic Workflow: Generating a Clean BC Sales Invoice

Once connected to Claude Code or GitHub Copilot, you can interact with Business Central report layouts using natural language instructions. The AI agent inspects your AL project, invokes the MCP tools, and delivers a verified .docx layout.

โ–ถ Sample Prompt to Claude Code

“Inspect the AL report StandardSalesInvoice.al in this workspace. Create a custom Word report layout that uses the BC 29 theme palette for table borders and header accents. Add a repeating table row for sales lines with alternating row shading, and place a payment remittance slip at the bottom that is conditionally configured to print strictly on the last page. Validate the OpenXML schema before saving.”

Under the hood, Claude Code executes a series of typed MCP tool calls:

  1. inspect_al_dataset: Extracts available dataset fields (Document No., Customer Name, Line Amount, VAT, Dimensions).
  2. initialize_word_layout: Creates a clean, uncorrupted OpenXML Word document container with proper BC XML namespaces.
  3. set_layout_theme: Applies the BC 29 theme palette, configuring dynamic theme colors for table borders.
  4. bind_repeating_table: Maps the Line dataitem to a structured Word table with clean repeating row controls.
  5. set_conditional_print_rule: Injects the last-page-only condition on the remittance slip block.
  6. validate_layout: Performs automated OpenXML schema validation against Microsoft Office and Business Central printing standards.

7. The Allgrow Perspective: AI-Led Velocity in Enterprise ERP

The release of tools like the BC Word Layout MCP server underscores exactly what we champion at Allgrow Technologies: AI-accelerated ERP engineering is not about replacing human ERP expertise; it is about eliminating mechanical friction so senior architects can focus on business value.

In traditional consulting engagements, formatting 15 to 20 customer-facing documents (invoices, packing slips, purchase orders, credit memos) consumes dozens of billable developer hours just wrestling with Word Developer tabs and XML mapping.

By integrating agentic MCP workflows into our development toolchain, Allgrow slashes report turnaround times by 70%, guarantees zero schema corruption, and delivers upgrade-safe documents ready for Microsoft’s upcoming BC 29 release wave.

Accelerate Your Business Central Modernization with Allgrow

From AI-accelerated AL development and MCP agent workflows to seamless BC 29 upgrades and 24/7 SLA-backed managed support, Allgrow Technologies engineers resilient Microsoft ERP systems for enterprises nationwide.

8. Frequently Asked Questions (FAQ)

What is the Model Context Protocol (MCP)?
Model Context Protocol (MCP) is an open standard developed by Anthropic that enables AI assistants (like Claude, GitHub Copilot, and Cursor) to connect to external development tools, databases, and local file systems through typed, secure interfaces. Rather than predicting raw text, the AI executes structured actions via the MCP server.
Why use Word report layouts instead of RDLC or Excel in Business Central?
Word layouts are ideal for branded customer-facing documents (Sales Invoices, Quotes, Packing Slips) because business users can modify typography, logos, and margin settings using familiar Microsoft Word desktop tools without needing SQL Server Report Builder. RDLC is preferred for complex multi-grouping financial statements, while Excel layouts excel at analytical data slicing.
Can the BC Word Layout MCP server break older Business Central environments?
No. The MCP server automatically parses your AL extension’s app.json file. If your target version is older than BC 29, the server actively blocks BC 29-only features (such as dynamic report theme bindings or specific vertically merged cell structures), ensuring backwards compatibility for production environments.
Where can I find the open-source repository for BC Word Layout local MCP?
The tool is open-source and hosted on GitHub under the BC developer community. You can find the repository and release notes directly on GitHub, install it as a plugin for Claude Code or VS Code, or run it via dnx from NuGet.

Connect with Allgrow Technologies

100% Free ยท No Obligation

Need an Objective Architecture or Code Assessment?

Discuss your Dynamics 365, Business Central, or Power Platform environment in a free 30-minute session with our senior engineers.

Get a Free 30-Minute Review โ†’
Chat on WhatsApp