🚀 MCP Server Workshop - Business Central Integration

Choose a route

Learn MCP locally: start without BC credentials; src/config.py permits mock mode. Create the venv and run python test_server.py from the repository root. The expected result is MCP tool discovery using sample data; it does not validate Entra authentication or live BC.

Connect your own BC sandbox: configure .env from .env.example, authorize the application and company, then verify a read with your own client. Do not mix a successful mock test with a successful BC API call.

The root contains server_workshop.py, setup.ps1, setup.sh, ConfigurationPaths.ps1, test_server.py and validate_workshop.py; src/ and data/ contain modules and samples. No root scripts/ or tests/ directory is supplied. Static documentation review: 6 October 2026; no dependency installation or MCP invocation performed. No applicable license file confirmed.

Welcome to the MCP Server Workshop! This workshop teaches you to build a complete MCP (Model Context Protocol) server with STDIO transport for Claude Desktop, integrated with Microsoft Dynamics 365 Business Central.

⏱️ Workshop Duration: 20-30 minutes
📖 Complete Workshop Guide →
🚀 Quick Start Guide → (Setup + Exercises)
📊 Presentation Slides: MCP_Server_Custom Directions.pptx

---

🎯 Workshop Objectives

Learn to build, extend, and customize MCP servers with:

• ✅ MCP Protocol fundamentals
• ✅ STDIO transport for Claude Desktop integration
• ✅ Business Central API integration
• ✅ Custom tools and prompts creation
• ✅ Practical exercises for hands-on learning

---

📋 Prerequisites

Before starting the workshop, ensure you have:

Required:

• 🐍 Python 3.12 or higher installed (Download here)
• 💻 Claude Desktop app installed (Download here)
• 📦 Basic command line knowledge (terminal/PowerShell)

Only required for the real Business Central route:

• 🏭 Azure AD Tenant with Business Central access
• Business Central Environment with Standard API v2.0 enabled:
• Sandbox or Production environment
• API endpoints: /api/v2.0/companies, /items, /customers, /salesOrders, etc.
• Company name and Environment name
• 🚀 Azure AD App Registration configured:
  • Client ID, Client Secret, Tenant ID
  • API permissions for Business Central (Dynamics 365 Business Central)
  • Redirect URI configured (if needed)

Local MCP learning route (mock data):

• 🧪 Mock Data Mode: The workshop includes mock data as a fallback
  • Allows completing exercises without real BC connection
  • Limited to testing MCP protocol mechanics
  • Does not demonstrate real authentication or API integration
  • Use the real BC route when authentication and live APIs are your learning objective

Good to Know:

• ✅ Virtual environment setup is automated via scripts
• ✅ All Python dependencies are listed in requirements.txt
• 🧪 Mock data available only as fallback if BC access unavailable

---

📚 Quick Start

📥 Step 1: Download the Repository

1. Go to: https://github.com/javiarmesto/Workshop-MCP-Server-Directions-Lab
2. Click the green “Code” button
3. Select “Download ZIP”
4. Extract the ZIP file to your desired location
5. Open a terminal and navigate to the extracted folder:

   cd Workshop-MCP-Server-Directions-Lab-main
   

🚀 Step 2: Automated Setup (Recommended - 2 minutes)

For Windows PowerShell:

# Run the automated setup script
.\setup.ps1

# For help and options:
.\setup.ps1 -Help

# Force recreate virtual environment:
.\setup.ps1 -Force

For macOS/Linux:

# Make script executable and run
chmod +x setup.sh
./setup.sh

The automated scripts will:

• [OK] Auto-detect Python installation (no PATH required)
• [OK] Check Python version (3.12+ required)
• [OK] Create and activate virtual environment
• [OK] Install all dependencies automatically
• [OK] Verify the installation works
• [OK] Show you next steps

Important: The setup script automatically finds Python in common locations. You don’t need to add Python to your system PATH.

📋 Manual Setup (5 minutes)

# 1. Download and extract
# Go to: https://github.com/javiarmesto/Workshop-MCP-Server-Directions-Lab
# Click "Code" → "Download ZIP"
# Extract the ZIP file
# Navigate to the extracted folder:
cd Workshop-MCP-Server-Directions-Lab-main

# 2. Install dependencies
python -m venv workshop-env

# Activate virtual environment
# Windows PowerShell:
.\workshop-env\Scripts\Activate.ps1
# Windows CMD:
workshop-env\Scripts\activate.bat
# macOS/Linux:
source workshop-env/bin/activate

# Install dependencies (ensure virtual environment is activated!)
pip install -r requirements.txt

# 3. Configure credentials (optional - works with mock data)
cp .env.example .env
# Edit .env with your Azure AD and Business Central credentials
# Example:
# AZURE_TENANT_ID=your-tenant-id-guid
# AZURE_CLIENT_ID=your-app-registration-client-id
# AZURE_CLIENT_SECRET=your-app-registration-secret
# BC_ENVIRONMENT=production
# BC_COMPANY_ID=your-company-guid

# 4. Test the server works
python ./test_server.py

Expected output: The test script will show all available MCP tools:

[SUCCESS] Server responded!

============================================================
AVAILABLE TOOLS:
============================================================

1. get_customers - Get customer list from Business Central
2. get_items - Get items list from Business Central
3. get_sales_orders - Get sales orders from Business Central
... (6 tools total)

[SUCCESS] Test completed successfully!

💡 Quick test: Use python test_server.py to verify your server is working correctly

🚨 Having setup issues? See the workshop guide for setup troubleshooting!

Visual Testing with MCP Inspector (Optional)

Before configuring Claude Desktop, you can test your server visually with MCP Inspector:

Install MCP Inspector:

# Quick (no installation required)
npx @modelcontextprotocol/inspector

# Or install globally
npm install -g @modelcontextprotocol/inspector
mcp-inspector

Get Configuration Paths:

# Run the configuration paths script
.\ConfigurationPaths.ps1

This script will display:

• Python executable path
• Server script path
• Workshop path
• Claude Desktop format (JSON with forward slashes /)
• MCP Inspector format (Windows with backslashes \)

Configure in MCP Inspector UI:

1. Transport Type: Select STDIO
2. Command: Paste the python.exe path (Windows format with backslashes)
3. Arguments: Paste the server_workshop.py path (Windows format)
4. Environment Variables (optional):
   • Key: PYTHONPATH
   • Value: Your workshop path

Test Your Server:

• Click “Connect” to start the server
• Browse the Tools tab to see all 6 available tools
• Click any tool and fill parameters to test it
• Check Prompts tab for customer_analysis and pricing_analysis
• Inspect Resources tab to view available data files

Benefits:

• ✅ Visual interface for debugging
• ✅ Test tools individually without Claude Desktop
• ✅ Inspect JSON request/response data
• ✅ Faster iteration during development

📖 For detailed instructions, see Step 6-7 in WORKSHOP_GUIDE_EN.md

Configure with Claude Desktop

Option A: Automated Configuration (Recommended) ⚡

# Run the automated configuration script
.\configure_claude.ps1

This script will:

• ✅ Auto-detect all required paths
• ✅ Backup your existing configuration
• ✅ Create/update Claude Desktop config with correct paths and PYTHONPATH
• ✅ Validate the JSON configuration
• ✅ Open the config file for review
• ✅ Show you the next steps

Then restart Claude Desktop and start using your MCP tools!

---

Option B: Manual Configuration

Get your paths first:

# Run the configuration paths script
.\ConfigurationPaths.ps1

Copy the paths from the “FOR CLAUDE DESKTOP (JSON format)” section.

Edit your Claude Desktop configuration file:

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

Configuration template (replace paths with yours):

{
  "mcpServers": {
    "bc-workshop-server": {
      "command": "YOUR_PYTHON_PATH_HERE",
      "args": ["YOUR_SERVER_PATH_HERE"],
      "env": {
        "PYTHONPATH": "YOUR_WORKSHOP_PATH_HERE"
      }
    }
  }
}

⚠️ Important: Include the "env" field with PYTHONPATH to ensure proper module loading.

💡 Quick validation: Run Get-Content "$env:APPDATA\Claude\claude_desktop_config.json" | ConvertFrom-Json to test your JSON.

Then restart Claude Desktop and start using your MCP tools!

---

📖 Documentation

• 📘 Complete Workshop Guide - Step-by-step instructions with architecture diagrams
• 🔧 Troubleshooting - Common issues and solutions

---

📁 Repository Structure

The checkout contains these paths:

Workshop-MCP-Server-Directions-Lab/
├── 📄 server_workshop.py           # Main MCP server (STDIO transport)
├── 📄 validate_workshop.py         # Validation script
├── 📄 test_server.py               # Quick server test (lists tools)
├── 📄 requirements.txt             # Python dependencies
├── 📄 setup.ps1                    # Automated setup (Windows)
├── 📄 setup.sh                     # Automated setup (macOS/Linux)
├──  ConfigurationPaths.ps1       # Get paths for Claude Desktop & MCP Inspector
├── 🔒 .env.example                 # Environment template
├── 📖 README.md                    # This file
├── 📖 QUICK_START_GUIDE.md         # Quick start instructions
├── 📖 WORKSHOP_GUIDE_EN.md         # Complete step-by-step guide
│
├── 📁 src/                         # Source code modules
│   ├── azure_auth.py               # Azure AD authentication
│   ├── client.py                   # Business Central client
│   └── config.py                   # Configuration
│
└── 📁 data/                        # Sample data
    ├── README.md                   # Data files documentation
    ├── categories.csv              # Product categories
    ├── prices.csv                  # Price and stock data
    ├── substitutes.csv             # Product substitutions
    ├── sales_orders.csv            # Mock sales orders
    ├── payment_terms.csv           # Mock payment terms
    └── price-analysis.json         # Price analysis data

---

🔧 Prerequisites

Software Requirements

• Python 3.12+ (verify: python --version)
• pip (verify: pip --version)
• Claude Desktop - Download from claude.ai
• Text editor (VS Code, PyCharm, etc.)
• Terminal/Command line access

Business Central Access (Optional)

With Business Central access:

• 🏢 Azure AD Tenant with Business Central access
• 🔑 App Registration in Azure AD (Client ID, Client Secret, Tenant ID)
• 🌍 BC Environment name (production or sandbox)
• 📋 BC Company ID

Without Business Central access:

• ✅ The workshop works with mock data included in the data/ folder
• ✅ You can complete all exercises using sample CSV files
• ✅ Perfect for learning MCP concepts without external dependencies

Knowledge Prerequisites

Beginner-friendly, but helpful to know:

• Basic Python programming
• JSON format
• Command line usage

---

🎓 What is STDIO Transport?

STDIO (Standard Input/Output) transport enables MCP servers to communicate with clients through stdin/stdout streams. This is the standard method for integrating MCP servers with Claude Desktop.

Key Benefits:

• ⚡ Fast local communication
• 🔒 No network exposure (secure by default)
• 🎯 Perfect for Claude Desktop integration
• ⚙️ Simple configuration - no ports or networking required

How it works:

1. Claude Desktop launches your MCP server as a subprocess
2. Communication happens via standard input/output streams
3. JSON-RPC messages are exchanged over these streams
4. The server provides tools, prompts, and resources to Claude

STDIO vs HTTP Transport

While this workshop focuses on STDIO transport for Claude Desktop, MCP also supports HTTP-based transport for different use cases:

---

🛠️ Using This Template

This repository serves as a complete, working template. You can:

1. Run immediately with Claude Desktop

   • The server works with mock data out of the box
   • No external dependencies required

2. Study the implementation

   • See how tools, prompts, and resources are built
   • Understand MCP protocol patterns

3. Extend with your own features

   • Add new tools following the examples
   • Create custom prompts for your use case

4. Connect to your own APIs

   • Replace Business Central with any API
   • Adapt the patterns to your needs

---

🛠️ How to Extend

Understanding the MCP Server Components

The workshop server demonstrates three main MCP capabilities:

1️⃣ Tools (Functions Claude can call)

• Located in: server_workshop.py → handle_list_tools() and handle_call_tool()
• Examples: get_customers, get_items, get_currency_exchange_rates
• How to add your own:

  # In handle_list_tools(), add:
  types.Tool(
      name="your_tool_name",
      description="What your tool does",
      inputSchema={
          "type": "object",
          "properties": {
              "param1": {"type": "string", "description": "Parameter description"}
          }
      }
  )
  
  # In handle_call_tool(), add:
  elif tool_name == "your_tool_name":
      result = await client.your_api_method(arguments.get("param1"))
      return [types.TextContent(type="text", text=json.dumps(result))]
  

2️⃣ Prompts (Pre-configured Claude prompts)

• Located in: server_workshop.py → handle_list_prompts() and handle_get_prompt()
• Examples: customer_analysis, vendor_analysis
• How to add your own:

  # In handle_list_prompts(), add:
  types.Prompt(
      name="your_prompt_name",
      description="What your prompt does",
      arguments=[
          types.PromptArgument(
              name="param1",
              description="Parameter description",
              required=True
          )
      ]
  )
  
  # In handle_get_prompt(), add case for your prompt
  

3️⃣ Resources (Static data files)

• Located in: server_workshop.py → handle_list_resources() and handle_read_resource()
• Examples: CSV and JSON files in data/ folder
• How to add your own:

  # In handle_list_resources(), add:
  types.Resource(
      uri=AnyUrl("file://data/your_file.csv"),
      name="Your Resource Name",
      description="What this resource contains",
      mimeType="text/csv"
  )
  

Practical Workshop Exercise

The repository includes working examples you can study:

• ✅ vendor_analysis prompt: Example of adding a new prompt
• ✅ get_currency_exchange_rates tool: Example of adding a new tool
• ✅ Test suite: test_server.py and validate_workshop.py provide local validation entry points

---

📖 Additional Resources

🆘 Support

If you encounter problems:

1. 📖 Review the Troubleshooting section in WORKSHOP_GUIDE_EN.md
2. 🔍 Check logs in Claude Desktop (View → Developer → Developer Tools)
3. 🌐 Verify credentials if using Business Central
4. ✅ Run python validate_workshop.py to check your setup

📚 Learning More

• MCP Specification: spec.modelcontextprotocol.io
• MCP Documentation: modelcontextprotocol.io
• Claude Desktop: claude.ai

---

🚀 Enjoy building with MCP and Business Central!

Workshop Duration: 20-30 minutes • Focus: STDIO Transport • Based on MCP SDK