bc-webclient-mcp

v2.5.1

Published

15 days ago

Model Context Protocol (MCP) server for Microsoft Dynamics 365 Business Central via WebUI protocol. Enables AI assistants to interact with BC through the web client protocol, supporting Card, List, and Document pages with full line item support and server

0High
0Medium
0Low

sshadows

mcp model-context-protocol business-central dynamics-365 bc erp microsoft ai llm assistant claude websocket jsonrpc api integration

🚀 BC WebClient MCP

Model Context Protocol server for Microsoft Dynamics 365 Business Central via WebUI protocol

Features • Quick Start • Tools • Documentation • Architecture

📖 Overview

BC WebClient MCP is a Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with Microsoft Dynamics 365 Business Central through a clean, intuitive interface. Built by reverse-engineering BC's WebUI WebSocket protocol, it provides real-time access to ERP data, business logic, and operations.

What is MCP?

The Model Context Protocol is an open standard that enables AI assistants to securely connect with external data sources and tools. This server implements MCP to bridge Claude with Business Central's internal APIs.

Why This Matters

Business Central's web client uses an undocumented WebSocket protocol for all UI operations. This project reverse-engineers the WebUI protocol (not official APIs) to:

✅ Enable AI-driven ERP automation - Let Claude interact with BC data naturally
✅ No custom extensions required - Works with vanilla BC installations
✅ Real-time operations - Leverage BC's live WebSocket connection
✅ Production-ready - Built on BC's actual internal protocol (the same one the web UI uses)

✨ Features

Version 2.5 Highlights

Workflow Tracking - Track multi-step business processes with start_workflow, get_workflow_state, end_workflow
Dialog Handling - Full handle_dialog tool for template selection, confirmations, and prompts
Document Line Items - Write to subpages/repeaters with subpage, lineBookmark, lineNo parameters
Document Pages - Full support for Sales Orders, Purchase Orders with header + line items
MCP Resources - Access BC schema, workflows, and session state
MCP Prompts - Guided workflows for common operations
Multi-Page Support - Card, List, and Document pages all work reliably

🔍 Discovery & Search

Tell Me search integration (Alt+Q)
Page metadata extraction
Field and action discovery
Dynamic form inspection

📊 Data Operations

Read page data in real-time
Filter and query list pages
Create and update records
Execute page actions
NEW: Document pages with line items

🔐 Authentication

Session-based web authentication
Support for all BC auth types
CSRF token management
Automatic session handling

⚡ Performance

Event-driven architecture
Gzip compression support
Connection pooling ready
Efficient state management

🚀 Quick Start

Get up and running with BC WebClient MCP in 5 minutes.

Prerequisites

Node.js 18 or higher (Download)
Business Central v27.0 (other versions may work but are not tested - protocol specifics are BC 27)
Valid BC credentials with web client access
Claude Desktop (Download) or any MCP-compatible client

Step 1: No Installation Required!

The MCP server runs directly via npx - no installation needed. Just configure Claude Desktop in the next step.

Step 2: Configure Claude Desktop

Find your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Edit the config file and add the MCP server (replace with your BC credentials):

{
  "mcpServers": {
    "business-central": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "bc-webclient-mcp@latest"
      ],
      "env": {
        "BC_BASE_URL": "http://your-bc-server/BC/",
        "BC_USERNAME": "your-username",
        "BC_PASSWORD": "your-password",
        "BC_TENANT_ID": "default"
      }
    }
  }
}

Note: On macOS/Linux, use "command": "sh" and "args": ["-c", "npx bc-webclient-mcp@latest"] instead.

Why npx?

✅ No installation required - runs directly from npm
✅ Always uses the latest version automatically
✅ No need to manage global packages

Important notes:

Use BC_USERNAME=username, NOT domain\username
The tenant is handled automatically in the URL parameter
For BC Online, use your full BC URL (e.g., https://businesscentral.dynamics.com/...)

Step 3: Restart Claude Desktop

Restart Claude Desktop completely to load the MCP server.

Step 4: Verify It's Working

Open a new chat in Claude Desktop and try:

Search for customer pages

You should see Claude using the search_pages tool and returning BC pages. If the MCP server appears in the tools list (🔧 icon), you're all set!

🎉 What You Can Do Now

Try these commands to explore v2 capabilities:

Document Pages with Line Items:

Read Sales Order 101001 with all line items

Smart Search:

Find all pages related to inventory management

Resources (Schema Discovery):

What BC pages are available?

(Uses the bc://schema/pages resource)

Guided Workflows (Prompts):

Create a new customer named Acme Corporation

(Uses the create_bc_customer prompt for step-by-step guidance)

Data Operations:

Show me customers where balance is over 10000

Field Updates:

Update customer 10000's credit limit to 50000

🔧 Quick Troubleshooting

MCP server not showing up in Claude Desktop?

Check the config file syntax is valid JSON
Restart Claude Desktop completely (close all windows)
Verify Node.js is installed: node --version (requires 18+)
Check Claude Desktop logs: View → Developer → Toggle Developer Tools → Console

Connection failed?

Verify BC is accessible: Open http://your-bc-server/BC/ in a browser
Check BC_BASE_URL includes the /BC/ path
Ensure firewall allows WebSocket connections

Authentication error?

Test login in browser first
Use username WITHOUT domain prefix (just username)
Verify tenant ID matches your BC installation (default for on-prem)

"TypeScript errors" when building?

Run npx tsc --noEmit to see detailed errors
Ensure Node.js version is 18 or higher: node --version

For more troubleshooting, see CLAUDE.md

📦 Alternative: Install from Source

For development, testing unreleased features, or contributing to the project:

# Clone the repository
git clone https://github.com/SShadowS/bc-webclient-mcp-server.git
cd bc-webclient-mcp-server

# Install dependencies
npm install

# Build the TypeScript project
npm run build

Then in Claude Desktop config, use the local path:

{
  "mcpServers": {
    "business-central": {
      "command": "node",
      "args": ["C:\\path\\to\\bc-webclient-mcp-server\\dist\\index.js"],
      "env": {
        "BC_BASE_URL": "http://your-bc-server/BC/",
        "BC_USERNAME": "your-username",
        "BC_PASSWORD": "your-password",
        "BC_TENANT_ID": "default"
      }
    }
  }
}

Note: Use full absolute paths with double backslashes on Windows.

Available Tools

The MCP server provides 10 tools for AI interaction:

Core Tools (7)

| Tool | Description | Level | |------|-------------|-------| | search_pages | Search for pages using Tell Me (Alt+Q) | Discovery | | get_page_metadata | Get page structure, fields, and actions | Discovery | | read_page_data | Read data from a page (with server-side filtering) | Read | | write_page_data | Write field values with validation, supports subpage/line operations | Write | | execute_action | Execute page actions (New, Edit, Post, etc.) | Action | | select_and_drill_down | Navigate between pages via drill-down | Navigation | | handle_dialog | Handle BC dialogs (template selection, confirmations) | Dialog |

Workflow Tools (3)

| Tool | Description | |------|-------------| | start_workflow | Begin tracking a multi-step business process | | get_workflow_state | Query workflow state, history, and unsaved changes | | end_workflow | Complete workflow with final status |

Optional/Advanced Tools

| Tool | Description | |------|-------------| | create_record_by_field_name | Create records using field names (convenience wrapper) |

Tool Architecture

The MCP server provides tools at multiple levels:

Core Tools - Essential primitives for BC interaction:

write_page_data - Write fields with immediate validation, subpage/line support
execute_action - Execute any page action with auto-resolved controlPath
handle_dialog - Handle dialogs with row selection and button clicks

Workflow Tools - Track multi-step business processes:

start_workflow → perform operations with workflowId → end_workflow
Tracks unsaved changes, operation history, and errors

Convenience Tools - Higher-level wrappers:

create_record_by_field_name - Simplified record creation using field names

Example Usage

Once connected, you can interact with Business Central through Claude:

You: "Search for customer-related pages"
Claude: [Uses search_pages tool]
Found 21 customer pages:
- Page 21: Customer Card
- Page 22: Customer List
...

You: "Show me customers where balance is over 10000"
Claude: [Uses read_page_data with filters]
Found 5 customers with balance > 10000:
1. Contoso Ltd - Balance: 15,234.50
2. Fabrikam Inc - Balance: 12,890.00
...

You: "Update customer 10000's credit limit to 50000"
Claude: [Uses get_page_metadata, execute_action("Edit"), write_page_data, execute_action("Save")]
Updated customer successfully:
- Opened Customer Card for customer 10000
- Switched to Edit mode
- Updated Credit Limit: 50,000.00
- Saved changes

You: "Add a line to Sales Order 101001"
Claude: [Uses write_page_data with subpage parameter]
Added line to Sales Order:
- Item No.: 1000
- Quantity: 5
- Line created successfully

🔐 Security & User Consent

User Consent Flow

This MCP server implements the MCP 2025 user consent requirement to ensure users maintain control over all data-modifying operations.

How It Works

Tool Classification: Each tool is classified by risk level:
- 🟢 Low Risk (read-only) - No consent required
- 🟡 Medium Risk (writes) - User approval required
- 🔴 High Risk (irreversible) - User approval + warning

Consent Enforcement: Claude Desktop shows approval dialog before executing write operations:

⚠️  Tool Execution Request

Claude wants to execute: create_record

Create a new record in Business Central?
This will add data to your Business Central database.

[Deny]  [Allow]

Audit Trail: All approved operations are logged with:
- Timestamp
- Tool name
- Input summary (sanitized)
- Execution result

Tool Consent Requirements

| Tool | Requires Consent | Risk Level | Reason | |------|------------------|------------|--------| | search_pages | No | Low | Read-only discovery | | get_page_metadata | No | Low | Read metadata only | | read_page_data | No | Low | Read-only data access | | start_workflow | No | Low | Creates tracking state only | | get_workflow_state | No | Low | Read workflow state | | end_workflow | No | Low | Marks workflow complete | | write_page_data | Yes | Medium | Direct field writes | | select_and_drill_down | Yes | Medium | Navigation with selection | | handle_dialog | Yes | Medium | Can bypass safety prompts | | create_record_by_field_name | Yes | Medium | Creates new data | | execute_action | Yes | High | Can trigger Post/Delete |

Audit Log Access

Audit logs are available via structured logging (Pino). Example log entry:

{
  "level": "info",
  "msg": "Tool execution audit",
  "toolName": "create_record",
  "userApproved": true,
  "result": "success",
  "timestamp": "2025-11-08T10:30:45.123Z",
  "inputSummary": {
    "pageId": "21",
    "fields": "[Object]"
  }
}

Sensitive Data Protection: The audit logger automatically redacts passwords, tokens, API keys, secrets, and other credential fields.

For more details, see docs/TOOL-CONSENT-CLASSIFICATION.md and docs/USER-CONSENT-GUIDE.md.

🏗️ Architecture

Protocol Stack

┌─────────────────────────────────────┐
│     Claude Desktop (AI Client)      │
└──────────────┬──────────────────────┘
               │ MCP Protocol
               │ (JSON-RPC over stdio)
┌──────────────▼──────────────────────┐
│         MCP Server (Node.js)        │
│  ┌────────────────────────────┐    │
│  │   Tool Registry            │    │
│  │   - search_pages           │    │
│  │   - filter_list            │    │
│  │   - get_page_metadata      │    │
│  │   - ...                    │    │
│  └────────────┬───────────────┘    │
│               │                     │
│  ┌────────────▼───────────────┐    │
│  │  BCRawWebSocketClient      │    │
│  │  - Session management      │    │
│  │  - Event-driven handlers   │    │
│  │  - Gzip compression        │    │
│  └────────────┬───────────────┘    │
└───────────────┼─────────────────────┘
                │ WebSocket + JSON-RPC
                │ (BC Internal Protocol)
┌───────────────▼─────────────────────┐
│  Business Central Web Service       │
│  /BC/csh endpoint (WebSocket)       │
└─────────────────────────────────────┘

Key Components

BCRawWebSocketClient - Core WebSocket client that mimics browser behavior
MCPServer - MCP protocol implementation (JSON-RPC over stdio)
BaseMCPTool - Base class for all MCP tools with error handling
Protocol Parsers - Decode BC's internal handler arrays
Event Emitters - Handle asynchronous BC responses

How It Works

Authentication: Web login flow → Session cookies + CSRF token
WebSocket Connection: Connect to /csh with session credentials
Session Opening: OpenSession request → Extract session identifiers
Event-Driven Operations: Send Invoke requests → Wait for handler arrays
Response Parsing: Decompress gzip → Parse handler structures → Extract data

For deep technical details, see:

ARCHITECTURE.md - Complete architecture analysis
BC-COPILOT-IMPLEMENTATION.md - BC's internal Copilot protocol
docs/FILTER_METADATA_SOLUTION.md - Filter implementation

📚 Documentation

Quick Reference

CLAUDE.md - Essential guide for development and troubleshooting
SETUP.md - Step-by-step setup instructions
ARCHITECTURE.md - System architecture and design decisions

Deep Dives

BC-COPILOT-IMPLEMENTATION.md - 🔥 Must Read! - BC's exact Copilot protocol
BC-AI-AGENT-ANALYSIS.md - BC's built-in AI agent framework
docs/FILTER_METADATA_SOLUTION.md - Filter tool implementation
docs/current/TELLME-SEARCH-STATUS.md - Tell Me search implementation

External Resources

🧪 Development

Project Structure

bc-poc/
├── src/
│   ├── core/                    # Core infrastructure
│   │   ├── errors.ts            # Error types and handling
│   │   ├── result.ts            # Result monad for error handling
│   │   └── interfaces.ts        # TypeScript interfaces
│   ├── services/                # Business logic
│   │   ├── BCRawWebSocketClient.ts   # ⭐ Main WebSocket client
│   │   ├── mcp-server.ts        # MCP protocol server
│   │   └── stdio-transport.ts   # stdin/stdout JSON-RPC transport
│   ├── tools/                   # MCP tool implementations
│   │   ├── search-pages-tool.ts
│   │   ├── filter-list-tool.ts
│   │   ├── get-page-metadata-tool.ts
│   │   └── ...
│   ├── protocol/                # BC protocol parsers
│   │   ├── logical-form-parser.ts
│   │   └── handler-types.ts
│   └── types/                   # TypeScript type definitions
├── test/                        # Test scripts
├── docs/                        # Detailed documentation
└── dist/                        # Compiled JavaScript (generated)

Development Commands

# Type checking (run frequently!)
npx tsc --noEmit

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test
npm run test:coverage

# Test specific functionality
npm run test:invoke        # Test Invoke method
npm run test:mcp          # Test MCP server

Code Quality Standards

⚠️ NO STUBS POLICY: This is a production codebase. Do NOT create:

Stub implementations
Mock functions that don't actually work
Placeholder code with "not yet implemented" errors
Tools that are registered but non-functional

Every feature MUST be fully implemented and functional before being committed.

Testing

# Run all tests
npm test

# Run specific test suites
npm run test:mcp:client          # MCP client integration tests
npm run test:mcp:real           # Real BC integration tests

# Test Tell Me search
npx tsx test-tellme-search.ts "customer"

# Test MCP server with real BC connection
npm run test:mcp:real:client

🤝 Contributing

Contributions are welcome! Please:

Read the architecture documentation first
Follow the existing code style and patterns
Ensure TypeScript compilation passes (npx tsc --noEmit)
Add tests for new functionality
Update documentation as needed

Key Guidelines

Use Windows paths when working on Windows
Run type checking regularly with npx tsc --noEmit
No stubs or mocks - all implementations must be fully functional
Read CLAUDE.md for development guidelines
Check existing docs before implementing new features

📋 Requirements

Supported Business Central Versions

✅ Business Central v27.0 (fully tested and supported)
⚠️ Other versions (v24-v26, v28+) may work but are not tested
- Protocol specifics are hardcoded for BC 27
- Older/newer versions may have different WebSocket protocol implementations
- Use at your own risk - contributions for other versions welcome!
✅ On-Premises installations (BC 27)
✅ Business Central Online (BC 27)

Authentication Support

✅ NavUserPassword (username/password)
✅ Windows Authentication
✅ Azure AD (via web login)

No special BC configuration required! The server mimics browser login behavior.

🐛 Troubleshooting

Connection Issues

# Test BC connectivity
curl http://your-server/BC/

# Check BC service status (on-prem)
docker exec Cronus27 powershell "Get-Service 'MicrosoftDynamicsNavServer*'"

# Verify WebSocket endpoint
wscat -c ws://your-server/BC/csh

Common Issues

"WebSocket connection failed"

Verify BC_BASE_URL is correct and includes /BC/ path
Ensure BC web client is accessible in browser first
Check firewall rules

"Authentication failed"

Test login in browser: http://your-server/BC/
Use username WITHOUT domain prefix (just username, not domain\username)
Verify tenant ID is correct

"CSRF token not found"

Ensure BC web client is accessible
Check if BC requires different authentication
Clear BC cache and restart services

"OpenSession timeout"

Verify tenant ID matches your BC installation
Check BC server logs for errors
Increase timeout in BCRawWebSocketClient

For more troubleshooting tips, see CLAUDE.md.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built on Microsoft Dynamics 365 Business Central
Implements the Model Context Protocol by Anthropic
Inspired by BC's internal Copilot implementation

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Project Wiki

⬆ back to top

Made with ❤️ for the Business Central community

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

🚀 BC WebClient MCP

📖 Overview

What is MCP?

Why This Matters

✨ Features

Version 2.5 Highlights

🔍 Discovery & Search

📊 Data Operations

🔐 Authentication

⚡ Performance

🚀 Quick Start

Prerequisites

Step 1: No Installation Required!

Step 2: Configure Claude Desktop

Step 3: Restart Claude Desktop

Step 4: Verify It's Working

🎉 What You Can Do Now

🔧 Quick Troubleshooting

📦 Alternative: Install from Source

Available Tools

Core Tools (7)

Workflow Tools (3)

Optional/Advanced Tools

Tool Architecture

Example Usage

🔐 Security & User Consent

User Consent Flow

How It Works

Tool Consent Requirements

Audit Log Access

🏗️ Architecture

Protocol Stack

Key Components

How It Works

📚 Documentation

Quick Reference

Deep Dives

External Resources

🧪 Development

Project Structure

Development Commands

Code Quality Standards

Testing

🤝 Contributing

Key Guidelines

📋 Requirements

Supported Business Central Versions

Authentication Support

🐛 Troubleshooting

Connection Issues

Common Issues

📄 License

🙏 Acknowledgments

📞 Support