Windows 365 MCP Server

A comprehensive MCP server that enables AI assistants to discover, provision, and manage Windows 365 Cloud PCs through Microsoft Graph API. Built with C#/.NET and fully compliant with MCP specification 2025-06-18. Initial set of tools is provided, while we will continue building and providing tools. Initial release uses STDIO while future releases will also include Streamable HTTP as a transport.

Table of Contents

• What's Included
• Key Features
• Prerequisites
• Quick Start
• What You Can Do Now
• MCP Tools (AI Actions)
• MCP Prompts (Guided Workflows)
• MCP Resources (Live Data)
• Common Use Cases
• Troubleshooting
• Architecture
• Authentication & Transport
• Security & Compliance
• MCP Client Examples
• Roadmap
• Testing & Validation
• Windows 365 Provisioning Flow
• Contributing
• License
• About UNITONE
• Support & Community

✨ What's Included

🛠️ MCP Tools (AI-Controlled Actions)

• 13 Tools: Windows 365 discovery, monitoring, licensing, user management, and policy administration
• Comprehensive coverage of Windows 365 operations from read-only discovery to license assignments

💬 MCP Prompts (User-Guided Workflows)

• 6 Prompts: Cloud PC troubleshooting, policy analysis, license optimization, deployment planning, user provisioning, security assessment
• Pre-built workflows for common Windows 365 scenarios

📊 MCP Resources (Real-Time Data Access)

• 7 Resources: Cloud PCs list, individual PC details, provisioning policies, licenses, user licenses, groups list, tenant summary
• Live inventory, health monitoring, and documentation

🔧 MCP Utilities

• Completion: Windows 365-specific autocompletion for tools and prompts
• Pagination: Cursor-based pagination for large datasets
• Logging: Structured logging compliant with MCP standards

🔐 Enterprise Security

• DefaultAzureCredential: Secure authentication with multiple credential sources
• STDIO Transport: MCP-compliant communication protocol
• Structured Logging: All logs to stderr for proper MCP protocol separation

---

🚀 Key Features

• ✅ Full MCP Compliance - Complete implementation of MCP 2025-06-18 specification with official C# SDK
• ✅ Zero-Config Discovery - Automatic Cloud PC and license detection via Microsoft Graph API
• ✅ Production Authentication - DefaultAzureCredential with environment variable support
• ✅ Real-Time Data - Live Cloud PC inventory, policies, and license information
• ✅ Enterprise Security - Secure STDIO transport with structured logging
• ✅ Production Ready - Tested with real Windows 365 tenants and Graph API endpoints

📋 Prerequisites

• .NET 9.0 SDK
• Windows 365 tenant with active subscriptions
• Entra ID App Registration with Microsoft Graph permissions

⚡ Quick Start

Follow these exact steps for successful setup:

Step 1: Clone & Build Project

git clone https://github.com/unitone-ai/windows-365-mcp-server.git
cd windows-365-mcp-server
dotnet restore src/Windows365.Mcp.Server/Windows365.Mcp.Server.csproj
dotnet build src/Windows365.Mcp.Server/Windows365.Mcp.Server.csproj

Step 2: Configure Entra ID App Registration

1. Go to Azure Portal → App registrations → New registration
2. Name: Windows 365 MCP Server
3. Redirect URI: Leave blank (not needed for STDIO transport)
4. After creation, go to API permissions and grant these Application permissions:
   • CloudPC.ReadWrite.All
   • User.Read.All
   • Group.Read.All
   • Directory.Read.All
   • LicenseAssignment.ReadWrite.All
   • DeviceManagementConfiguration.ReadWrite.All
5. Click Grant admin consent for your organization (this is required!)
6. Go to Certificates & secrets → New client secret → Copy the secret value
7. Copy the Application (client) ID and Directory (tenant) ID from the Overview page

Step 3: Configure Authentication (.env file)

Important: Create a .env file in the project root directory:

# Copy the template
cp .env.template .env

# Edit .env with your actual values from Step 2
AZURE_TENANT_ID=your-tenant-id-from-overview-page
AZURE_CLIENT_ID=your-client-id-from-overview-page
AZURE_CLIENT_SECRET=your-client-secret-from-step-6

Example .env file:

AZURE_TENANT_ID=12345678-1234-1234-1234-123456789012
AZURE_CLIENT_ID=87654321-4321-4321-4321-210987654321
AZURE_CLIENT_SECRET=abcdef123456789~something.very.long.and.secret

Step 4: Test the Server (Optional)

Test the server with MCP Inspector:

# Test the server directly 
dotnet run --project src/Windows365.Mcp.Server/Windows365.Mcp.Server.csproj

# Or run with MCP Inspector for interactive testing
npx @modelcontextprotocol/inspector dotnet run --project .

This will start MCP Inspector at http://localhost:6274/ with session token authentication.

Configure MCP Inspector (with your path):

• Transport: STDIO
• Command: dotnet
• Arguments: run --project /YOUR-FULL-PATH-HERE/src/Windows365.Mcp.Server
• Environment variables:

AZURE_TENANT_ID=YOUR-TENANT-ID
AZURE_CLIENT_ID=YOUR-CLIENT-ID
AZURE_CLIENT_SECRET=YOUR-CLIENT-SECRET

Step 5: Connect to Claude Desktop

5a. Find Your Claude Desktop Config File

Locate the config file:

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

5b. Get Your Project's Absolute Path

# Run this command in your project directory to get the full path
pwd
# Copy the output (example: /Users/yourname/windows-365-mcp-server)

5c. Edit Claude Desktop Configuration

Open the config file and add this exact configuration:

{
  "mcpServers": {
    "windows365": {
      "command": "dotnet",
      "args": ["run", "--project", "/YOUR-FULL-PATH-HERE/windows-365-mcp-server/src/Windows365.Mcp.Server"],
      "env": {
        "WINDOWS365_ENV_PATH": "/YOUR-FULL-PATH-HERE/windows-365-mcp-server/.env"
      }
    }
  }
}

The server will load your .env from the path set in WINDOWS365_ENV_PATH. Alternatively, you can set AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET directly in the env block instead of using a .env file.

5d. Final Steps

1. Save the file
2. Restart Claude Desktop completely (quit and reopen)
3. Start a new conversation in Claude Desktop
4. Verify it works: Ask Claude "What Windows 365 tools do you have available?"

✅ Success: You should see Claude respond with a list of Windows 365 management tools!

---

🎯 What You Can Do Now

Once setup is complete, you can ask Claude (or other MCP clients) things like:

• "Show me all Cloud PCs in our tenant"
• "Check the Windows 365 licenses in our organization"
• "Help me troubleshoot a Cloud PC issue"
• "Walk me through provisioning a new user"

The server provides 13 tools, 6 prompts, and 7 resources for comprehensive Windows 365 management.

---

🛠️ MCP Tools (AI Actions)

Total: 13 Tools across 4 categories for comprehensive Windows 365 management:

Cloud PC Discovery & Management (4 tools)

Tool	Purpose	Type
DiscoverCloudPCs	List and filter Cloud PCs in Windows 365 tenant with search capabilities	Read-only
GetCloudPCDetails	Get detailed information about a specific Cloud PC	Read-only
EndGracePeriod	End the grace period for a specific Cloud PC immediately	Modifying
RebootCloudPC	Restart a specific Cloud PC	Modifying

User & Group Management (3 tools)

Tool	Purpose	Type
SearchUsers	Search and list users in the Entra ID tenant with advanced filtering capabilities	Read-only
GetUserDetails	Get detailed information about a specific user including license assignments and memberships	Read-only
SearchGroups	Search and list groups in the Entra ID tenant with provisioning policy associations	Read-only

License Management (4 tools)

Tool	Purpose	Type
CheckUserLicenses	Check Windows 365 license assignments for a specific user	Read-only
GetWindows365Licenses	Get Windows 365 licenses including availability information for consumed and available licenses	Read-only
AssignLicense	Assign a Windows 365 license to a user	Modifying
UnassignLicense	Unassign a Windows 365 license from a user	Modifying

Provisioning Policy Management (2 tools)

Tool	Purpose	Type
GetProvisioningPolicies	Get all provisioning policies in the Windows 365	Read-only
GetProvisioningPolicyDetails	Get detailed information about a specific provisioning policy with assignments	Read-only

Example: Discover All Cloud PCs

{
  "name": "DiscoverCloudPCs",
  "arguments": {
    "top": 50
  }
}

Result: List of all Cloud PCs with status and user assignments

Example: Get Specific Cloud PC Details

{
  "name": "GetCloudPCDetails",
  "arguments": {
    "cloudPcId": "12345678-1234-1234-1234-123456789012"
  }
}

Result: Complete Cloud PC information including service plan, provisioning policy, and device details

Example: Get All Windows 365 Licenses

{
  "name": "GetWindows365Licenses",
  "arguments": {}
}

Result: Complete list of all Windows 365 licenses including consumed and available units, with availability calculations

---

💬 MCP Prompts (Guided Workflows)

Prompt	Scenario	What It Does
cloud_pc_troubleshoot	IT Support	Guides through Cloud PC diagnostic workflows
provisioning_policy_analysis	IT Admin	Analyze and optimize provisioning policies
license_optimization	Finance/IT	Analyze and optimize license allocation
deployment_planning	IT Planning	Create deployment plans for Windows 365 rollouts
user_provisioning	IT Admin	Guide Cloud PC provisioning workflow for new users
security_assessment	Security	Assess Windows 365 security configuration

Example Usage in Claude

Use the "cloud_pc_troubleshoot" prompt for a user experiencing slow performance

Claude will guide through diagnostic steps including checking Cloud PC status, service plan adequacy, and common performance issues.

---

📊 MCP Resources (Live Data)

Resource	Data Type	Content
windows365://cloudpcs	JSON	Complete Cloud PC inventory with real-time status
windows365://cloudpc/{id}	JSON	Detailed information about a specific Cloud PC
windows365://provisioning-policies	JSON	All provisioning policies and their configurations
windows365://licenses	JSON	License availability and usage information
windows365://user-licenses/{userId}	JSON	License details for a specific user
windows365://groups	JSON	List of Entra ID groups in the tenant
windows365://tenant-summary	JSON	Tenant overview and summary statistics

Example: Access Live Inventory

Claude can access windows365://cloudpcs to get real-time Cloud PC data including:

• Current status of all Cloud PCs
• User assignments and service plans
• Provisioning policy associations
• Last modified timestamps and device information

---

🎯 Common Use Cases

🔍 Cloud PC Discovery & Inventory

"Show me all Cloud PCs in our tenant"
→ Uses DiscoverCloudPCs tool
→ Provides complete inventory with status and user assignments

🔧 Cloud PC Details & Management

"What are the details of Cloud PC xyz?"
→ Uses GetCloudPCDetails tool
→ Provides comprehensive Cloud PC information including service plan and device details

👥 User & Group Management

"Search for users with 'john' in their name"
→ Uses SearchUsers tool
→ Provides filtered list of users matching search criteria

"List all security groups"
→ Uses SearchGroups tool
→ Shows all groups in the Entra ID tenant

📈 License Analysis & Management

"Show me all Windows 365 licenses with availability information"
→ Uses GetWindows365Licenses tool
→ Provides complete license inventory with consumed and available units

"Check what licenses user xyz has"
→ Uses CheckUserLicenses tool
→ Shows specific user's Windows 365 license assignments

"Assign a Windows 365 license to user xyz"
→ Uses AssignLicense tool (Modifying)
→ Assigns available Windows 365 license to specified user

🏗️ Provisioning Policy Management

"List all provisioning policies"
→ Uses GetProvisioningPolicies tool
→ Shows all policies and their configurations

"Show me details for policy xyz including its assignments"
→ Uses GetProvisioningPolicyDetails tool
→ Provides complete policy information and group assignments

⚠️ Modifying Operations

"End grace period for Cloud PC xyz"
→ Uses EndGracePeriod tool (Modifying)
→ Immediately ends grace period for failed Cloud PC

"Assign license to user xyz"
→ Uses AssignLicense tool (Modifying)
→ Assigns Windows 365 license to specified user

"Remove Windows 365 license from user xyz"
→ Uses UnassignLicense tool (Modifying)
→ Removes Windows 365 license from specified user

---

🔧 Troubleshooting

Claude Desktop Connection Issues

Problem: Claude Desktop shows connection errors or tools are not available Solutions:

1. Check file paths: Ensure all paths in claude_desktop_config.json are absolute paths
2. Verify credentials: Confirm AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID are correct
3. Restart Claude Desktop: Always restart after config changes
4. Check config syntax: Ensure JSON is valid (no trailing commas, proper quotes)

Problem: "Unexpected token" or JSON parsing errors in Claude Desktop logs Solutions:

1. Verify absolute paths: Use full paths, not relative paths like ./ or ~/
2. Check .NET installation: Ensure .NET 9.0 SDK is installed and in PATH
3. Verify working directory: Ensure that WINDOWS365_ENV_PATH points to a real .env file.

MCP Inspector Issues

Problem: MCP Inspector won't connect to server Solutions:

1. Check server startup: Ensure server builds and runs without errors
2. Port conflicts: Check if port 6274 is available
3. Authentication errors: Use proper session token from inspector output

Authentication Issues

Problem: "DefaultAzureCredential failed" errors Solutions:

1. Environment variables: Verify AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID are set
2. App registration: Confirm Entra ID app has required Graph API permissions
3. Admin consent: Ensure admin consent has been granted for the application
4. Tenant access: Verify the service principal has access to Windows 365 resources

Performance Issues

Problem: Slow response times or timeouts Solutions:

1. Network connectivity: Check connectivity to graph.microsoft.com
2. Large datasets: Use pagination parameters (top, filters) for large queries
3. Token refresh: Authentication tokens are refreshed automatically

---

🏗️ Architecture

Windows365.Mcp.Server/
├── src/Windows365.Mcp.Server/
│   ├── Tools/                  # MCP Tools with [McpServerTool] attributes
│   ├── Prompts/                # MCP Prompts with [McpServerPrompt] attributes
│   ├── Resources/              # MCP Resources with [McpServerResource] attributes
│   ├── Services/               # Microsoft Graph API integration
│   ├── Authentication/         # DefaultAzureCredential provider
│   ├── Utilities/              # MCP utilities (pagination, etc.)
│   └── Program.cs              # MCP Server with STDIO transport
├── .env.template               # Environment variable template
└── README.md                   # This documentation

🔐 Authentication & Transport

Current Implementation: STDIO Transport

Important: This server currently uses STDIO transport with Azure Identity authentication, which is recommended for local hosting and trusted environments where credentials can be securely retrieved from the environment.

As per the MCP Authorization specification, implementations using STDIO transport SHOULD NOT follow the OAuth 2.1 authorization specification. Instead, credentials are retrieved from the environment through:

• Azure CLI authentication (az login) - Recommended for development
• Environment variables - For automated/service scenarios
• Managed Identity - When running in Azure
• DefaultAzureCredential chain - Automatic fallback through multiple auth methods

This approach is appropriate for:

• ✅ Local development environments
• ✅ Trusted server deployments
• ✅ Service-to-service authentication
• ✅ Azure-hosted applications with Managed Identity

🔐 Security & Compliance

DefaultAzureCredential Authentication

• Multiple credential source support (environment variables, managed identity, etc.)
• Secure token management with automatic refresh
• No hardcoded credentials in source code

MCP Security Best Practices

• STDIO transport for secure communication
• Structured logging to stderr (MCP compliant)
• Input validation and sanitization
• Proper error handling and logging

Enterprise Controls

• Microsoft Graph API permissions (Application level)
• Entra ID tenant-scoped access
• Complete audit trail through Entra ID logs
• Rate limiting via Microsoft Graph throttling

📱 MCP Client Examples

See the Windows 365 MCP Server in action with different MCP clients:

MCP Inspector

Ideal for testing MCP functionality and exploring available tools

Claude Desktop

Production AI assistant with Windows 365 management capabilities

VS Code

Development environment with integrated Windows 365 tools

🛣️ Roadmap

v2.0 - HTTP Transport & OAuth 2.1 Support

We plan to add HTTP transport support following the MCP specification's OAuth 2.1 authorization framework for broader deployment scenarios:

OAuth 2.1 Authorization Implementation

• OAuth 2.1 Authorization Server - Full authorization server implementation
• Access token validation - Proper scope management and token verification
• Dynamic client registration - Support for client registration workflows
• Authorization Code flow with PKCE - Secure authorization for public clients

HTTP Transport Features

• HTTP transport layer - For remote server deployment beyond local hosting
• Streamable HTTP - Real-time updates and streaming capabilities
• RESTful endpoints - HTTP-based MCP protocol implementation
• Session management - Secure session handling for web-based clients

Additional Provisioning Policy Tools

Complete provisioning policy lifecycle management:

• 🏗️ Create Provisioning Policies - Full policy creation with configuration options
• 📝 Update Provisioning Policies - Modify existing policy settings and assignments
• 🗑️ Delete Provisioning Policies - Remove unused or obsolete policies
• 👥 Policy Group Assignments - Assign and manage group-to-policy mappings

These tools will provide complete Windows 365 provisioning policy management capabilities through AI assistants.

---

🧪 Testing & Validation

This server has been tested with real Windows 365 tenants including:

✅ Authentication - DefaultAzureCredential with Microsoft Graph
✅ API Endpoints - All Microsoft Graph calls validated
✅ MCP Protocol - Full compliance with specification 2025-06-18 using official C# SDK ✅ Tools Functionality - All 13 MCP tools tested and working ✅ Resources Access - All 7 MCP resources returning live data ✅ Prompts Integration - All 6 MCP prompts properly structured

Test Results

• 1 Cloud PC discovered and detailed information retrieved
• 2 Windows 365 license SKUs detected with flexible pattern matching (handles invisible Unicode characters)
• Provisioning policies successfully enumerated
• All 13 MCP tools tested and working correctly
• All MCP protocol methods (initialize, tools/list, prompts/list, resources/list, etc.) working correctly
• Enhanced license detection with comprehensive SKU pattern support for Enterprise, Business, and Shared Use editions
• License assignment functionality tested and working

---

🚀 Windows 365 Provisioning Flow

Understanding the Windows 365 provisioning workflow:

graph LR
    A[User] --> B[License Assignment]
    B --> C[Group Membership]  
    C --> D[Provisioning Policy]
    D --> E[Auto-Provisioning]
    E --> F[Cloud PC Ready]

1. License Assignment (Immediate)
2. Group Membership (Immediate)
3. Policy Application (Immediate)
4. Auto-Provisioning (30-60 minutes)
5. User Access (Additional 5-10 minutes)

The following MCP tools are available for Windows 365 management:

Cloud PC Discovery & Management

• DiscoverCloudPCs - List all Cloud PCs in the organization
• GetCloudPCDetails - Get detailed information about a specific Cloud PC
• EndGracePeriod - End grace period for failed Cloud PC provisioning
• RebootCloudPC - Restart a specific Cloud PC

User & Group Management

• SearchUsers - Search for users in the organization
• GetUserDetails - Get detailed information about a specific user
• SearchGroups - Search for Azure AD groups

License Management

• CheckUserLicenses - Check Windows 365 license assignments for users
• GetWindows365Licenses - List available Windows 365 licenses in the tenant
• AssignLicense - Assign Windows 365 license to a user
• UnassignLicense - Remove Windows 365 license from a user

Provisioning Policy Management

• GetProvisioningPolicies - List all provisioning policies
• GetProvisioningPolicyDetails - Get detailed information about a specific provisioning policy

These tools work together to automate the complete Windows 365 provisioning workflow.

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---