bc-mcp-proxy 0.1.3

Python-based MCP stdio proxy for Microsoft Dynamics 365 Business Central

Business Central MCP Proxy (Python)

⚠️ Experimental Tool - Not for Production Use

This tool is for experimentation only and is not intended for production use. It allows you to connect Cursor, VS Code, Claude Desktop, or other MCP-compatible clients to a Business Central Model Context Protocol (MCP) server.

Overview

The BC MCP Proxy acts as a bridge between MCP-compatible clients (like Cursor, VS Code, Claude Desktop) and Business Central, enabling natural language interactions with your Business Central data and operations. This Python implementation is published as bc-mcp-proxy on PyPI.

Why a Python Version?

This Python implementation was created to provide a simpler, cross-platform alternative to the .NET version. Key differences:

• Easier Installation: Install directly from PyPI with a single command (pip install bc-mcp-proxy), no need to build or download executables
• Cross-Platform: Works on Windows, macOS, and Linux without platform-specific builds
• Unified Setup: Interactive setup command (python3 -m bc_mcp_proxy setup on macOS/Linux, python -m bc_mcp_proxy setup on Windows) handles configuration, authentication, and generates client configs automatically
• Better IDE Integration: Works seamlessly with Cursor, VS Code, and other MCP clients that expect Python-based tools
• Same Functionality: Provides the same MCP proxy capabilities as the .NET version, connecting stdio-based MCP clients to Business Central's MCP HTTP endpoint

Both versions provide the same core functionality—choose the Python version if you prefer easier installation and cross-platform support, or the .NET version if you prefer a compiled executable.

Prerequisites

• Microsoft Dynamics 365 Business Central environment with MCP preview feature enabled
• Azure tenant with appropriate permissions
• Python 3.10 or later
• MCP-compatible client (Cursor, VS Code, Claude Desktop, etc.)

Setup Instructions

1. Set-up Azure AD App Registration

1. Open ms.portal.azure.com

2. Navigate to Microsoft Entra ID and create a new App Registration

3. In the Authentication section, add the desktop app Redirect URL in the format:

   ms-appx-web://Microsoft.AAD.BrokerPlugin/<clientID>
   

   Also enable "Allow public client flows" under the Authentication section.

4. Add the following API permissions:

   Required permissions:

   • Dynamics 365 Business Central (2)
     • Financials.ReadWrite.All (Delegated)
     • user_impersonation (Delegated)

2. Install and Configure the Proxy

1. Install Python 3.10+ from python.org if not already installed.

2. Run the unified setup command in a terminal (PowerShell, Command Prompt, bash, zsh, etc.):

   Windows:

   python -m pip install --upgrade bc-mcp-proxy && python -m bc_mcp_proxy setup
   

   macOS/Linux:

   python3 -m pip install --upgrade bc-mcp-proxy && python3 -m bc_mcp_proxy setup
   

   The interactive setup will:

   • Prompt for your Business Central tenant ID, client ID, environment, and company
   • Launch the device-code login flow (so you sign in immediately)
   • Generate ready-to-click install URLs for Cursor and VS Code plus a Claude Desktop snippet
   • Save everything under ~/.bc_mcp_proxy/ (or %USERPROFILE%\.bc_mcp_proxy\ on Windows)

3. Configure Your MCP Client

   The setup command generates ready-to-use configuration files and install links:

   • Cursor/VS Code: Use the clickable install link printed by setup, or copy the generated cursor_mcp.json or vscode_mcp.json from ~/.bc_mcp_proxy/ into your MCP configuration
   • Claude Desktop: Copy the generated claude_mcp.json snippet into your claude_desktop_config.json

4. Restart Your MCP Client

   After adding the configuration, restart your MCP client. You should see Business Central tools available in your client.

Usage

Once configured, you can interact with Business Central through natural language in your MCP client. The proxy will handle authentication and API calls to your Business Central environment.

Example interactions:

• "Show me the latest sales orders"
• "Create a new customer record"
• "What are the current inventory levels?"
• "List all customers"

Configuration Parameters

Parameter	CLI Argument	Environment Variable	Description	Required
Tenant ID	--TenantId	BC_TENANT_ID	Azure tenant identifier	Yes
Client ID	--ClientId	BC_CLIENT_ID	Azure app registration client ID	Yes
Environment	--Environment	BC_ENVIRONMENT	Business Central environment name (default: Production)	Yes
Company	--Company	BC_COMPANY	Business Central company name	Yes
Configuration Name	--ConfigurationName	BC_CONFIGURATION_NAME	Name of the Business Central configuration	No
Custom Auth Header	--CustomAuthHeader	BC_CUSTOM_AUTH_HEADER	Pre-issued bearer token (skips device flow)	No
Base URL	--BaseUrl	BC_BASE_URL	Base API URL (default: https://api.businesscentral.dynamics.com)	No
Token Scope	--TokenScope	BC_TOKEN_SCOPE	OAuth scope (default: https://api.businesscentral.dynamics.com/.default)	No
Log Level	--LogLevel	BC_LOG_LEVEL	Logging level (default: INFO)	No
Debug	--Debug	BC_DEBUG=1	Enable verbose logging	No

When no custom bearer token is supplied, the proxy performs a device-code flow. Tokens are cached using msal-extensions under:

• Windows: %LOCALAPPDATA%\BcMCPProxyPython\bc_mcp_proxy.bin
• macOS: ~/Library/Caches/BcMCPProxyPython/bc_mcp_proxy.bin
• Linux: $XDG_CACHE_HOME/BcMCPProxyPython/bc_mcp_proxy.bin (or ~/.cache/...)

Running the Proxy

After setup, you can run the proxy manually using the command printed by setup, or with:

Windows:

python -m bc_mcp_proxy --TenantId "<tenant-id>" --ClientId "<client-id>" --Environment "<environment>" --Company "<company>"

macOS/Linux:

python3 -m bc_mcp_proxy --TenantId "<tenant-id>" --ClientId "<client-id>" --Environment "<environment>" --Company "<company>"

Note: On macOS/Linux, if you see a PATH warning during installation, you can either:

• Add the script directory to your PATH (e.g., export PATH="$HOME/Library/Python/3.12/bin:$PATH" in ~/.zshrc or ~/.bashrc)
• Or always use python3 -m bc_mcp_proxy instead of the bc-mcp-proxy command

When the proxy logs Connecting to Business Central MCP endpoint... followed by device-code instructions, sign in (if prompted). The proxy stays running until you stop it.

Configuration files, logs, and generated MCP snippets are stored at:

• Windows: %USERPROFILE%\.bc_mcp_proxy\
• macOS/Linux: ~/.bc_mcp_proxy/

Re-run python3 -m bc_mcp_proxy setup (macOS/Linux) or python -m bc_mcp_proxy setup (Windows) at any time to update or regenerate these files.

Troubleshooting

Common Issues

1. Authentication Failures

   • Verify the redirect URL format in your Azure app registration: ms-appx-web://Microsoft.AAD.BrokerPlugin/<clientID>
   • Ensure "Allow public client flows" is enabled in your Azure app registration
   • Ensure all required API permissions are granted
   • Check that admin consent has been provided if required
   • If device flow times out, rerun setup

2. Connection Issues

   • Verify the Business Central environment name is correct
   • Ensure the company name matches exactly (case-sensitive)
   • Check network connectivity to Business Central
   • Confirm the environment supports MCP preview feature

3. MCP Client Not Detecting Server

   • Verify the Python path in your MCP configuration is correct (use python3 on macOS/Linux, python on Windows)
   • Check that the bc-mcp-proxy package is installed (run python3 -m pip list | grep bc-mcp-proxy on macOS/Linux, or python -m pip list | findstr bc-mcp-proxy on Windows)
   • If using a virtual environment, ensure the MCP client uses the correct Python interpreter
   • Restart your MCP client after configuration changes

4. "No module named bc_mcp_proxy" Error

   • Install the package globally: python3 -m pip install --upgrade bc-mcp-proxy (macOS/Linux) or python -m pip install --upgrade bc-mcp-proxy (Windows)
   • Or use --user flag: python3 -m pip install --user --upgrade bc-mcp-proxy (macOS/Linux) or python -m pip install --user --upgrade bc-mcp-proxy (Windows)
   • Or update your MCP config to use the full path to the Python interpreter that has the package installed
   • On macOS/Linux, if you see a PATH warning, use python3 -m bc_mcp_proxy instead of the bc-mcp-proxy command

5. Repeated Sign-in Prompts

   • The token cache may not be writable. Set --DeviceCacheLocation to a directory you control
   • Check file permissions on the cache directory

6. Business Central API Errors

   • Confirm the environment supports MCP and the company name is spelled exactly (case-sensitive)
   • Verify your Azure app has the correct API permissions

Security Considerations

• This tool uses delegated permissions and requires user authentication
• Credentials are handled through Azure's authentication flow
• No passwords or secrets are stored in configuration files
• Tokens are cached securely using msal-extensions with platform-specific secure storage
• Always follow your organization's security policies when setting up integrations

Support

This is an experimental tool provided as-is for development and testing purposes. For Business Central specific issues, consult the official Microsoft Dynamics 365 Business Central documentation.

License

Licensed under the MIT License (see LICENSE).