Workshop MCP Server Directions Lab
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.
Ask AI about Workshop MCP Server Directions Lab
Powered by Claude Β· Grounded in docs
I know everything about Workshop MCP Server Directions Lab. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
π 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
- Go to: https://github.com/javiarmesto/Workshop-MCP-Server-Directions-Lab
- Click the green "Code" button
- Select "Download ZIP"
- Extract the ZIP file to your desired location
- 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.pyto 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:
- Transport Type: Select
STDIO - Command: Paste the
python.exepath (Windows format with backslashes) - Arguments: Paste the
server_workshop.pypath (Windows format) - Environment Variables (optional):
- Key:
PYTHONPATH - Value: Your workshop path
- Key:
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_analysisandpricing_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 withPYTHONPATHto ensure proper module loading.π‘ Quick validation: Run
Get-Content "$env:APPDATA\Claude\claude_desktop_config.json" | ConvertFrom-Jsonto 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) |
|---------|---------------------------|----------------------------|
| **Transport** | stdin/stdout streams | HTTP + Server-Sent Events |
| **Use Case** | Claude Desktop integration | Web integrations, remote access |
| **Network** | Local only | Network-accessible |
| **Setup** | Simple | Requires port configuration |
| **Security** | Isolated by default | Needs HTTPS in production |
| **Best For** | Desktop apps, local tools | Cloud services, webhooks, APIs |
---
## π οΈ 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:**
```python
# 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()andhandle_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()andhandle_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_analysisprompt: Example of adding a new prompt - β
get_currency_exchange_ratestool: Example of adding a new tool - β
Test suite:
test_workshop_exercise.pyshows how to validate your additions
π Additional Resources
π Support
If you encounter problems:
- π Review the Troubleshooting section in WORKSHOP_GUIDE_EN.md
- π Check logs in Claude Desktop (View β Developer β Developer Tools)
- π Verify credentials if using Business Central
- β
Run
python tests/validate_workshop.pyto 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
