@microsoft/devbox-mcp

🏢 Dev Box MCP Server

This is a Model Context Protocol (MCP) server for Microsoft Dev Box, providing seamless integration between AI agents and Microsoft Dev Box services. This server enables natural language interactions for developer-focused operations like managing Dev Boxes, configurations, and pools.

🛠️ Currently Supported Tools

The Dev Box MCP provides tools for interacting with the following Microsoft Dev Box resources:

💻 Dev Box Lifecycle

• DevBox Resource: Single tool for DevBox discovery and information retrieval using scope patterns
  • List all DevBoxes across projects: /project/*/users/me/devboxes/*
  • List DevBoxes in specific project: /project/ProjectName/users/me/devboxes/*
  • Get specific DevBox details: /project/ProjectName/users/me/devboxes/DevBoxName
  • Query DevBox by name across projects: /project/*/users/me/devboxes/DevBoxName
• Create Dev Box: Provision a new Dev Box from a pool
• Delete Dev Box: Remove a Dev Box

📂 Projects

• List All Projects: View all accessible projects without specifying Dev Center
• List Projects: View all available Dev Center projects
• Get Project: Retrieve detailed project information
• Get Project Abilities: Get user's permitted abilities in a project

🏊 Dev Box Pools

• List Pools By Project: View all available Dev Box pools in a project

⚡ Power Management

• Change Dev Box Power State: Start, stop, or restart a Dev Box
• Repair Dev Box: Run automated repair steps to resolve common issues
• Get Remote Connection: Retrieve RDP connection information

🎯 Actions

• List Actions: View all actions for a Dev Box
• Skip Action: Skip an occurrence of an action
• Delay Action: Delay an action to a future time
• Delay All Actions: Delay all actions on a Dev Box until a specified time

📦 Customization

• List Customization Task Definitions By Project: View available customization tasks in a project
• Get Customization Task Definitions: Get details of a specific customization task
• Validate Customization Tasks: Validate a list of customization tasks
• List Customization Groups: View all customization groups for a Dev Box
• Get Customization Group: Get details of a specific customization group
• Create Customization Group: Apply customizations to a Dev Box
• Get Imaging Task Log: View logs for an imaging build task
• Run Tasks On Dev Box: Install packages or run commands on a Dev Box
• Get Customization Task Log: View logs for a customization task
• Set Dev Box Theme: Change the visual theme (dark/light) for a Dev Box

🔄 Operations

• Get Operation Status: Check status of long-running operations

🤔 Thinking

• DevBox Think: Provides context for understanding and performing Dev Box operations

🔌 Getting Started

Prerequisites

1. Node.js 18 or newer

2. Azure Resources

   • Azure subscription
   • Dev Center provisioned
   • At least one Dev Center project created
   • Appropriate RBAC permissions on Dev Center resources

3. MCP Client

• Install your MCP host/client of choice
• Recommended MCP clients include:
  • Visual Studio Code with GitHub Copilot extension
  • Visual Studio 2022 version 17.14 or later

Installation

Dev Box MCP Server can be installed on any MCP clients, such as Visual Studio or Visual Studio Code (VS Code). Below are the detailed steps for installing on Visual Studio Code.

For installation steps on Visual Studio, see here

✨ One-Click Install on VS Code

Click one of these buttons to install the Dev Box MCP Server for VS Code or VS Code Insiders.

Just one click, and you're ready to go! 🎉

🔧 Manual Install on VS Code

For a step-by-step installation, follow one of the following instructions:

1. Add .vscode/mcp.json to your workspace:

{
    "servers": {
        "Dev Box": {
            "command": "npx",
            "args": ["-y", "@microsoft/devbox-mcp@latest"]
        }
    }
}

2. Alternatively, add to your user settings.json:

{
    "mcp": {
        "servers": {
            "Dev Box": {
                "command": "npx",
                "args": ["-y", "@microsoft/devbox-mcp@latest"]
            }
        }
    }
}

3. You can also add Dev Box MCP programmatically using VS Code CLI:

# For VS Code
code --add-mcp '{"name":"Dev Box","command":"npx","args":["-y","@microsoft/devbox-mcp@latest"]}'

For detailed MCP installation steps on VS Code, see here.

🔑 Authentication

The Dev Box MCP Server uses DefaultAzureCredential and WAM (Web Account Manager) based brokered authentication for seamless Azure integration.

Authentication follows this credential chain order:

1. Environment Variables (EnvironmentCredential)
2. Managed Identity (ManagedIdentityCredential)
3. Visual Studio Code (VisualStudioCredential)
4. Azure CLI (AzureCliCredential)
5. Azure PowerShell (AzurePowerShellCredential)
6. Azure Developer CLI (AzureDeveloperCliCredential)
7. Windows SSO (Single Sign-On) (WAM - Web Account Manager)

The credential chain will attempt each method in order until a successful authentication is achieved. WAM provides seamless single sign-on experience on Windows platforms, automatically using your existing Windows credentials when available.

If you encounter authentication errors, try:

1. Make sure you're logged in to Windows SSO (Single Sign-On) or Azure CLI
2. Verify you have the necessary permissions in your Azure subscription
3. Check if you need to specify a specific tenant using az login --tenant <tenant-id>

❓ Frequently Asked Questions

Tool call failed with 'Tool xxx does not have an implementation registered' or 'I apologize for the technical issue'

If you encounter this error, it's likely due to an invalid tool cache issue in GitHub Copilot Agent mode. To resolve the issue:

1. Press Ctrl+Shift+P to open the command palette
2. Run MCP: Reset cached tools
3. Restart the MCP server

For more details, see GitHub issue #177

🛡️ License

Copyright (c) Microsoft Corporation. All rights reserved.