Dynamics 365 Finance & Operations MCP Server

Production-ready Model Context Protocol (MCP) server that exposes the full capabilities of Microsoft Dynamics 365 Finance & Operations (D365 F&O) to AI assistants and other MCP-compatible tools. This enables sophisticated Dynamics 365 integration workflows through standardized protocol interactions.

🚀 One-Click Installation for VS Code:

🐳 Docker Installation for VS Code:

☁️ Deploy to Azure Container Apps:

# Download and run the deployment script
curl -O https://raw.githubusercontent.com/mafzaal/d365fo-client/main/deploy-aca.sh
chmod +x deploy-aca.sh

# Set authentication (choose OAuth or API Key)
export D365FO_MCP_AUTH_CLIENT_ID="your-client-id"
export D365FO_MCP_AUTH_CLIENT_SECRET="your-client-secret"
export D365FO_MCP_AUTH_TENANT_ID="your-tenant-id"
# OR
export D365FO_MCP_API_KEY_VALUE="your-secret-key"

# Deploy
./deploy-aca.sh

1. Download azure-deploy.json
2. Go to Azure Portal → Deploy a custom template
3. Click "Build your own template in the editor"
4. Paste the contents of azure-deploy.json
5. Fill in the parameters and deploy

Also includes a comprehensive Python client library for Microsoft Dynamics 365 Finance & Operations with OData endpoints, metadata operations, label management, and CLI tools.

The d365fo-client includes a production-ready Model Context Protocol (MCP) server (d365fo-fastmcp-server) built on the FastMCP framework that exposes the full capabilities of D365 Finance & Operations to AI assistants and other MCP-compatible tools.

The server provides multi-transport support (stdio, HTTP, SSE) with enhanced performance and deployment flexibility.

• 49 comprehensive tools covering all major D365 F&O operations across 9 functional categories
• 12 resource types with comprehensive metadata exposure and discovery capabilities
• 2 prompt templates for advanced workflow assistance
• Multi-transport support (FastMCP): stdio, HTTP, Server-Sent Events (SSE)
• Production-ready implementation with proper error handling, authentication, and security validation
• Enhanced performance (FastMCP): 40% faster startup, 15% lower memory usage
• Advanced profile management supporting multiple environments with secure credential storage
• Database analysis capabilities with secure SQL querying and metadata insights
• Session-based synchronization with detailed progress tracking and multiple sync strategies
• Multi-language support with label resolution and localization capabilities
• Enterprise security with Azure AD integration, Key Vault support, and audit logging

• 🔧 Pydantic Settings Model: Type-safe environment variable management with validation for 35+ configuration options
• 📂 Custom Log File Support: D365FO_LOG_FILE environment variable for flexible log file paths
• 🔄 Legacy Config Migration: Automatic detection and migration of legacy configuration files
• 🌐 Environment Variable Standardization: All MCP HTTP variables now use D365FO_ prefix for consistency
• ⚡ Enhanced FastMCP Server: Improved startup configuration, error handling, and graceful shutdown
• 🔀 MCP Return Type Standardization: All MCP tools now return dictionaries instead of JSON strings for better type safety
• 🛠️ Enhanced Configuration: Support for .env files and comprehensive environment variable documentation

# Install d365fo-client with MCP dependencies
pip install d365fo-client

# Set up environment variables
export D365FO_BASE_URL="https://your-environment.dynamics.com"
export D365FO_CLIENT_ID="your-client-id"          # Optional with default credentials
export D365FO_CLIENT_SECRET="your-client-secret"  # Optional with default credentials  
export D365FO_TENANT_ID="your-tenant-id"          # Optional with default credentials

The modern FastMCP implementation provides enhanced performance and multiple transport options:

# Development (stdio transport - default)
d365fo-fastmcp-server

# Production HTTP API
d365fo-fastmcp-server --transport http --port 8000 --host 0.0.0.0

# Real-time Web Applications (SSE)
d365fo-fastmcp-server --transport sse --port 8001 --host 0.0.0.0

Key Benefits:

• Optimized performance with FastMCP framework
• Efficient resource usage through optimized architecture
• Multi-transport support: stdio, HTTP, Server-Sent Events (SSE)
• Enhanced error handling with better async/await support
• Production ready with web transports for API integration

FastMCP Server with Default Credentials: Add to your VS Code mcp.json for GitHub Copilot with MCP:

{
  "servers": {
    "d365fo-fastmcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "d365fo-client@latest",
        "d365fo-fastmcp-server"
      ],
      "env": {
        "D365FO_BASE_URL": "https://your-environment.dynamics.com",
        "D365FO_LOG_LEVEL": "INFO"
      }
    }
  }
}

Option 2: Explicit Credentials For environments requiring service principal authentication:

{
  "servers": {
    "d365fo-fastmcp-server": {
      "type": "stdio", 
      "command": "uvx",
      "args": [
        "--from",
        "d365fo-client",
        "d365fo-fastmcp-server"
      ],
      "env": {
        "D365FO_BASE_URL": "https://your-environment.dynamics.com",
        "D365FO_LOG_LEVEL": "DEBUG",
        "D365FO_CLIENT_ID": "${input:client_id}",
        "D365FO_CLIENT_SECRET": "${input:client_secret}",
        "D365FO_TENANT_ID": "${input:tenant_id}"
      }
    }
  },
  "inputs": [
    {
      "id": "tenant_id",
      "type": "promptString",
      "description": "Azure AD Tenant ID for D365 F&O authentication",
      "password": true
    },
    {
      "id": "client_id", 
      "type": "promptString",
      "description": "Azure AD Client ID for D365 F&O authentication",
      "password": true
    },
    {
      "id": "client_secret",
      "type": "promptString", 
      "description": "Azure AD Client Secret for D365 F&O authentication",
      "password": true
    }
  ]
}

Option 3: Docker Integration For containerized environments and enhanced isolation:

{
  "servers": {
    "d365fo-fastmcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "d365fo-mcp:/home/mcp_user/",
        "-e",
        "D365FO_CLIENT_ID=${input:client_id}",
        "-e",
        "D365FO_CLIENT_SECRET=${input:client_secret}",
        "-e",
        "D365FO_TENANT_ID=${input:tenant_id}",
        "ghcr.io/mafzaal/d365fo-client:latest"
      ],
      "env": {
        "D365FO_LOG_LEVEL": "DEBUG",
        "D365FO_CLIENT_ID": "${input:client_id}",
        "D365FO_CLIENT_SECRET": "${input:client_secret}",
        "D365FO_TENANT_ID": "${input:tenant_id}"
      }
    }
  },
  "inputs": [
    {
      "id": "tenant_id",
      "type": "promptString",
      "description": "Azure AD Tenant ID for D365 F&O authentication",
      "password": true
    },
    {
      "id": "client_id",
      "type": "promptString",
      "description": "Azure AD Client ID for D365 F&O authentication",
      "password": true
    },
    {
      "id": "client_secret",
      "type": "promptString",
      "description": "Azure AD Client Secret for D365 F&O authentication",
      "password": true
    }
  ]
}

Benefits of Docker approach:

• Complete environment isolation and reproducibility
• No local Python installation required
• Consistent runtime environment across different systems
• Automatic dependency management with pre-built image
• Enhanced security through containerization
• Persistent data storage via Docker volume (d365fo-mcp)

Prerequisites:

• Docker installed and running
• Access to Docker Hub or GitHub Container Registry
• Network access for pulling the container image

FastMCP Server: Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "d365fo-fastmcp": {
      "command": "uvx",
      "args": [
        "--from",
        "d365fo-client",
        "d365fo-fastmcp-server"
      ],
      "env": {
        "D365FO_BASE_URL": "https://your-environment.dynamics.com",
        "D365FO_LOG_LEVEL": "INFO"
      }
    }
  }
}

Traditional MCP Server (Alternative):

{
  "mcpServers": {
    "d365fo": {
      "command": "uvx",
      "args": [
        "--from",
        "d365fo-client",
        "d365fo-fastmcp-server"
      ],
      "env": {
        "D365FO_BASE_URL": "https://your-environment.dynamics.com",
        "D365FO_LOG_LEVEL": "INFO"
      }
    }
  }
}

Benefits of uvx approach:

• Always uses the latest version from the repository
• No local installation required
• Automatic dependency management
• Works across different environments

The FastMCP server provides HTTP and SSE transports for web application integration:

import aiohttp
import json

async def call_d365fo_api():
    """Example: Using HTTP transport for web API integration"""
    
    # Start FastMCP server with HTTP transport
    # d365fo-fastmcp-server --transport http --port 8000
    
    mcp_request = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": "d365fo_query_entities",
            "arguments": {
                "entityName": "CustomersV3",
                "top": 10,
                "select": ["CustomerAccount", "Name"]
            }
        }
    }
    
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "http://localhost:8000/mcp",
            json=mcp_request,
            headers={"Content-Type": "application/json"}
        ) as response:
            result = await response.json()
            print(json.dumps(result, indent=2))

// Example: JavaScript client for real-time D365FO data
// Start FastMCP server: d365fo-fastmcp-server --transport sse --port 8001

const eventSource = new EventSource('http://localhost:8001/sse');

eventSource.onmessage = function(event) {
    const data = JSON.parse(event.data);
    console.log('Received D365FO data:', data);
    
    // Handle real-time updates from D365FO
    if (data.method === 'notification') {
        updateDashboard(data.params);
    }
};

// Send MCP requests via SSE
function queryCustomers() {
    const request = {
        jsonrpc: "2.0",
        id: Date.now(),
        method: "tools/call",
        params: {
            name: "d365fo_search_entities",
            arguments: {
                pattern: "customer",
                limit: 50
            }
        }
    };
    
    fetch('http://localhost:8001/sse/send', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify(request)
    });
}

from d365fo_client.mcp import D365FOMCPServer

# Create and run server with custom configuration
config = {
    "default_environment": {
        "base_url": "https://your-environment.dynamics.com",
        "use_default_credentials": True
    }
}

server = D365FOMCPServer(config)
await server.run()

Connect using any MCP-compatible client library:

from mcp import Client

async with Client("d365fo-fastmcp-server") as client:
    # Discover available tools
    tools = await client.list_tools()
    
    # Execute operations
    result = await client.call_tool(
        "d365fo_query_entities",
        {"entityName": "Customers", "top": 5}
    )

For containerized environments and production deployments:

Pull the Docker Image:

# Pull from GitHub Container Registry
docker pull ghcr.io/mafzaal/d365fo-client:latest

# Or pull a specific version
docker pull ghcr.io/mafzaal/d365fo-client:v0.2.3

Standalone Docker Usage:

# Run MCP server with environment variables
docker run --rm -i \
  -e D365FO_BASE_URL="https://your-environment.dynamics.com" \
  -e D365FO_CLIENT_ID="your-client-id" \
  -e D365FO_CLIENT_SECRET="your-client-secret" \
  -e D365FO_TENANT_ID="your-tenant-id" \
  -e D365FO_LOG_LEVEL="INFO" \
  -v d365fo-mcp:/home/mcp_user/ \
  ghcr.io/mafzaal/d365fo-client:latest

# Run CLI commands with Docker
docker run --rm -it \
  -e D365FO_BASE_URL="https://your-environment.dynamics.com" \
  -e D365FO_CLIENT_ID="your-client-id" \
  -e D365FO_CLIENT_SECRET="your-client-secret" \
  -e D365FO_TENANT_ID="your-tenant-id" \
  ghcr.io/mafzaal/d365fo-client:latest \
  d365fo-client entities --limit 10

Docker Compose Example:

version: '3.8'
services:
  d365fo-mcp:
    image: ghcr.io/mafzaal/d365fo-client:latest
    environment:
      - D365FO_BASE_URL=https://your-environment.dynamics.com
      - D365FO_CLIENT_ID=${D365FO_CLIENT_ID}
      - D365FO_CLIENT_SECRET=${D365FO_CLIENT_SECRET}
      - D365FO_TENANT_ID=${D365FO_TENANT_ID}
      - D365FO_LOG_LEVEL=INFO
    volumes:
      - d365fo-mcp:/home/mcp_user/
    stdin_open: true
    tty: true

volumes:
  d365fo-mcp:

Docker Benefits:

• Complete environment isolation and reproducibility
• No local Python installation required
• Consistent runtime environment across different systems
• Built-in dependency management
• Enhanced security through containerization
• Persistent data storage via Docker volumes
• Easy integration with orchestration platforms (Kubernetes, Docker Swarm)

• Standardized Interface: Consistent MCP protocol access to D365 F&O
• Rich Metadata: Self-describing entities and operations
• Type Safety: Schema validation for all operations
• Error Context: Detailed error information for troubleshooting

• Minimal Integration: Standard MCP client libraries
• Comprehensive Coverage: Full D365 F&O functionality exposed
• Performance Optimized: Efficient connection and caching strategies
• Well Documented: Complete API documentation and examples

• Secure Access: Enterprise-grade authentication (Azure AD, Managed Identity)
• Audit Logging: Complete operation tracking and monitoring
• Scalable Design: Connection pooling and session management
• Maintenance Friendly: Clear architecture and comprehensive test coverage

Connection Failures

# Test connectivity
d365fo-client version app --base-url https://your-environment.dynamics.com

# Check logs
tail -f ~/.d365fo-mcp/logs/mcp-server.log

Authentication Issues

# Verify Azure CLI authentication
az account show

# Test with explicit credentials
export D365FO_CLIENT_ID="your-client-id"
# ... set other variables
d365fo-fastmcp-server

Performance Issues

# Enable debug logging
export D365FO_LOG_LEVEL="DEBUG"

# Adjust connection settings
export D365FO_CONNECTION_TIMEOUT="120"
export D365FO_MAX_CONCURRENT_REQUESTS="5"

• Logs: Check ~/.d365fo-mcp/logs/mcp-server.log for detailed error information
• Environment: Use d365fo_get_environment_info tool to check system status
• Documentation: See MCP Implementation Summary for technical details
• Issues: Report problems at GitHub Issues

The server provides 49 comprehensive tools organized into functional categories:

• d365fo_test_connection - Test connectivity and authentication with performance metrics and error diagnostics
• d365fo_get_environment_info - Get comprehensive environment details including versions, configurations, and capabilities

• d365fo_query_entities - Simplified OData querying with 'eq' filtering, wildcard patterns, field selection, and pagination
• d365fo_get_entity_record - Retrieve specific records by key with expansion options and ETag support
• d365fo_create_entity_record - Create new entity records with validation and business logic execution
• d365fo_update_entity_record - Update existing records with partial updates and optimistic concurrency control
• d365fo_delete_entity_record - Delete entity records with referential integrity checking and cascading rules
• d365fo_call_action - Execute OData actions and functions for complex business operations
• d365fo_call_json_service - Call generic JSON service endpoints with parameter support and response handling

• d365fo_search_entities - Search entities by pattern with category filtering and full-text search capabilities
• d365fo_get_entity_schema - Get detailed entity schemas with properties, relationships, and label resolution
• d365fo_search_actions - Search available OData actions with binding type and parameter information
• d365fo_search_enumerations - Search system enumerations with keyword-based filtering
• d365fo_get_enumeration_fields - Get detailed enumeration member information with multi-language support
• d365fo_get_installed_modules - Retrieve information about installed modules and their configurations

• d365fo_get_label - Get single label text by ID with multi-language support and fallback options
• d365fo_get_labels_batch - Get multiple labels efficiently with batch processing and performance optimization

• d365fo_list_profiles - List all configured D365FO environment profiles with status information
• d365fo_get_profile - Get detailed configuration information for specific profiles
• d365fo_create_profile - Create new environment profiles with comprehensive authentication options
• d365fo_update_profile - Modify existing profile configurations with partial update support
• d365fo_delete_profile - Remove environment profiles with proper cleanup and validation
• d365fo_set_default_profile - Designate a specific profile as the default for operations
• d365fo_get_default_profile - Retrieve information about the currently configured default profile
• d365fo_validate_profile - Validate profile configurations for completeness and security compliance
• d365fo_test_profile_connection - Test connectivity and authentication for specific profiles
• d365fo_clone_profile - Clone existing profiles with customization options for new environments
• d365fo_search_profiles - Search profiles by pattern with filtering and sorting capabilities
• d365fo_get_profile_names - Get simplified list of available profile names for quick reference
• d365fo_import_profiles - Import profile configurations from external sources or backups
• d365fo_export_profiles - Export profile configurations for backup or deployment purposes

• d365fo_execute_sql_query - Execute SELECT queries against metadata database with security validation
• d365fo_get_database_schema - Get comprehensive database schema information including relationships
• d365fo_get_table_info - Get detailed information about specific database tables with sample data
• d365fo_get_database_statistics - Generate database statistics and analytics for performance monitoring

• d365fo_start_sync - Initiate metadata synchronization with various strategies and session tracking
• d365fo_get_sync_progress - Monitor detailed progress of sync sessions with time estimates
• d365fo_cancel_sync - Cancel running sync sessions with graceful cleanup
• d365fo_list_sync_sessions - List all active sync sessions with status and progress information
• d365fo_get_sync_history - Get history of completed sync sessions with success/failure status and statistics

• d365fo_download_srs_report - Download SQL Server Reporting Services (SRS) reports with parameter support
• d365fo_download_sales_confirmation - Download sales confirmation reports in various formats
• d365fo_download_purchase_order - Download purchase order documents with formatting options
• d365fo_download_customer_invoice - Download customer invoice reports with customization
• d365fo_download_free_text_invoice - Download free text invoice documents
• d365fo_download_debit_credit_note - Download debit and credit note reports

• d365fo_get_server_performance - Get server performance metrics and statistics
• d365fo_get_server_config - Get server configuration information and system settings
• d365fo_reset_performance_stats - Reset performance statistics and counters for fresh monitoring

📖 For detailed information about all MCP tools including usage examples and best practices, see the Comprehensive MCP Tools Introduction.

🤖 For AI agents and assistants, see the AI Agent Guide for structured workflows, best practices, and automation patterns.

The server exposes four types of resources for discovery and access:

Access entity metadata and sample data:

d365fo://entities/CustomersV3     # Customer entity with metadata and sample data
d365fo://entities/SalesOrders     # Sales order entity information
d365fo://entities/Products        # Product entity details

Access system-wide metadata:

d365fo://metadata/entities        # All data entities metadata (V2 cache)
d365fo://metadata/actions         # Available OData actions  
d365fo://metadata/enumerations    # System enumerations
d365fo://metadata/labels          # System labels and translations