SShadowS/bc-webclient-mcp-server

📖 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

🚀 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

📦 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)

Workflow Tools (3)

Optional/Advanced Tools

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

1. 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

2. 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]
   

3. Audit Trail: All approved operations are logged with:

   • Timestamp
   • Tool name
   • Input summary (sanitized)
   • Execution result

Tool Consent Requirements

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 and .

🏗️ 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

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

For deep technical details, see:

• - Complete architecture analysis
• - BC's internal Copilot protocol
• - Filter implementation

📚 Documentation

Quick Reference

• - Essential guide for development and troubleshooting
• - Step-by-step setup instructions
• - System architecture and design decisions

Deep Dives

• - 🔥 Must Read! - BC's exact Copilot protocol
• - BC's built-in AI agent framework
• - Filter tool implementation
• - Tell Me search implementation

External Resources

• Business Central API Documentation
• Model Context Protocol Specification
• WebSocket Protocol RFC 6455
• JSON-RPC 2.0 Specification

🧪 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:

1. Read the architecture documentation first
2. Follow the existing code style and patterns
3. Ensure TypeScript compilation passes (npx tsc --noEmit)
4. Add tests for new functionality
5. 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 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 .

📄 License

This project is licensed under the MIT License - see the 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:
• Discussions:
• Documentation: