@microsoft/devbox-mcp v0.0.1-beta.1

🏢 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

• List All Dev Boxes: Get all accessible Dev Boxes across all projects
• List Existing Dev Boxes in Project: View Dev Boxes that already exist in a specified project
• Get Dev Box Details: Retrieve details of a specific Dev Box
• Query Dev Box: Find a Dev Box when only the name is known
• Create Dev Box: Provision a new Dev Box from a pool
• Delete Dev Box: Remove a Dev Box
• Check User in Dev Box: Determine if the user is executing commands within 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. Visual Studio Code

   • 💫 Stable release or 🔮 Insiders release
   • GitHub Copilot Extension with Agent Mode enabled

3. Azure Resources

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

Installation

✨ One-Click Install

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

For a step-by-step installation, follow these instructions:

1. Add .vscode/mcp.json:

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

Alternatively, you can add using VS Code CLI:

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

🔑 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.