🚀 MCP Server Workshop - Business Central Integration

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)

Required for Business Central Integration (Workshop Objective):

• 🏭 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)

Alternative (Only if BC access is not available):

• 🧪 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
  • Not recommended for full workshop experience

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
./scripts/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\Activate.ps1
# Windows CMD:
workshop-env\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 tests/test_server.py to verify your server is working correctly

🚨 Having setup issues? See SETUP_TROUBLESHOOTING.md for common solutions!

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
• 🎓 Presentation Slides - For instructors teaching this workshop
• 🔧 Troubleshooting - Common issues and solutions

---

📁 Repository Structure

You should see this structure:

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) ├── 📄 test_workshop_exercise.py # Exercise tests ├── 📄 requirements.txt # Python dependencies ├── 📄 setup.ps1 # Automated setup (Windows) ├── 📄 setup.sh # Automated setup (macOS/Linux) ├── scripts/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](https://claude.ai/download)
- **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:

| Feature | **STDIO** (This Workshop) | **HTTP/SSE** (Alternative) |
|---------|---------------------------|-----------