From 7fd81a35646c8e0c5c91c024b5eeeb3f6c359aff Mon Sep 17 00:00:00 2001 From: Connie Yau Date: Tue, 30 Sep 2025 08:35:38 -0700 Subject: [PATCH] Updates instructions for Docker (#626) * Fix Docker build instructions. Make ServerName mandatory. * Update README and TROUBLESHOOTING. * Move to single line. * Update servers/Azure.Mcp.Server/TROUBLESHOOTING.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Add preamble and link to TROUBLESHOOTING --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 6 +-- CONTRIBUTING.md | 4 +- eng/scripts/Build-Docker.ps1 | 1 + servers/Azure.Mcp.Server/README.md | 20 +++----- servers/Azure.Mcp.Server/TROUBLESHOOTING.md | 54 +++++++++++++++++++++ 5 files changed, 66 insertions(+), 19 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f6b87491f..93c520f41 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -246,7 +246,7 @@ dotnet build ./eng/scripts/Build-Local.ps1 -DebugBuild # Docker image build -./eng/scripts/Build-Docker.ps1 +./eng/scripts/Build-Docker.ps1 -ServerName "Azure.Mcp.Server" ``` ### Testing Commands @@ -551,14 +551,14 @@ mcp.json configuration for local development: ### Docker Development ```powershell # Build local Docker image -./eng/scripts/Build-Docker.ps1 +./eng/scripts/Build-Docker.ps1 -ServerName "Azure.Mcp.Server" # Use in mcp.json { "servers": { "Azure MCP Server": { "command": "docker", - "args": ["run", "-i", "--rm", "--env-file", "/path/to/.env", "azure/azure-mcp:latest"] + "args": ["run", "-i", "--rm", "--env-file", "/path/to/.env", "azure-sdk/azure-mcp:"] } } } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 94ef6f872..38a13710a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -298,7 +298,7 @@ With the configuration in place, you can launch the MCP server directly from you To build a local image for testing purposes: -1. Execute: `./eng/scripts/Build-Docker.ps1`. +1. Execute: `./eng/scripts/Build-Docker.ps1 -ServerName "Azure.Mcp.Server"`. 2. Update `mcp.json` to point to locally built Docker image: ```json @@ -312,7 +312,7 @@ To build a local image for testing purposes: "--rm", "--env-file", "/full/path/to/.env" - "azure/azure-mcp:", + "azure-sdk/azure-mcp:", ] } } diff --git a/eng/scripts/Build-Docker.ps1 b/eng/scripts/Build-Docker.ps1 index 1462f9f24..d61f8e916 100644 --- a/eng/scripts/Build-Docker.ps1 +++ b/eng/scripts/Build-Docker.ps1 @@ -4,6 +4,7 @@ [CmdletBinding(DefaultParameterSetName='none')] param( [string] $VersionSuffix, + [Parameter(Mandatory=$true)] [string] $ServerName, [switch] $Trimmed, [switch] $DebugBuild diff --git a/servers/Azure.Mcp.Server/README.md b/servers/Azure.Mcp.Server/README.md index 14da98e80..a8dc07276 100644 --- a/servers/Azure.Mcp.Server/README.md +++ b/servers/Azure.Mcp.Server/README.md @@ -125,11 +125,7 @@ npm install -g @azure/mcp ### Docker -Pull the Docker image: [mcr.microsoft.com/azure-sdk/azure-mcp](https://mcr.microsoft.com/artifact/mar/azure-sdk/azure-mcp). - -```bash -docker pull mcr.microsoft.com/azure-sdk/azure-mcp -``` +Run the Azure MCP server as a Docker container for easy deployment and isolation. The container image is available at [mcr.microsoft.com/azure-sdk/azure-mcp](https://mcr.microsoft.com/artifact/mar/azure-sdk/azure-mcp).
Docker instructions @@ -144,12 +140,9 @@ AZURE_CLIENT_ID={YOUR_AZURE_CLIENT_ID} AZURE_CLIENT_SECRET={YOUR_AZURE_CLIENT_SECRET} ``` -#### Configure your MCP client to use Docker: +#### Configure your MCP client to use Docker -2. Add or update existing `mcp.json`. - - Replace `/full/path/to/your.env` with the actual `.env` file path. - - Optionally, use `--env` or `--volume` to pass authentication values. - - **Note:** When manually configuring Visual Studio and Visual Studio Code, use `servers` instead of `mcpServers` as the root object. +2. Add or update existing `mcp.json`. Replace `/full/path/to/your/.env` with the actual `.env` file path. ```json { @@ -161,16 +154,17 @@ AZURE_CLIENT_SECRET={YOUR_AZURE_CLIENT_SECRET} "-i", "--rm", "--env-file", - "/full/path/to/your.env", + "/full/path/to/your/.env", "mcr.microsoft.com/azure-sdk/azure-mcp:latest" ] } } } ``` -
+To use Azure Entra ID, review the [troubleshooting guide](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/TROUBLESHOOTING.md#using-azure-entra-id-with-docker). + # Usage ## Getting Started @@ -388,8 +382,6 @@ Telemetry collection is on by default. To opt out, set the environment variable `AZURE_MCP_COLLECT_TELEMETRY` to `false` in your environment. - - ## Contributing We welcome contributions to the Azure MCP Server! Whether you're fixing bugs, adding new features, or improving documentation, your contributions are welcome. diff --git a/servers/Azure.Mcp.Server/TROUBLESHOOTING.md b/servers/Azure.Mcp.Server/TROUBLESHOOTING.md index 5e1387a44..c2ddfd801 100644 --- a/servers/Azure.Mcp.Server/TROUBLESHOOTING.md +++ b/servers/Azure.Mcp.Server/TROUBLESHOOTING.md @@ -34,6 +34,7 @@ This guide helps you diagnose and resolve common issues with the Azure MCP Serve - [Network and Firewall Restrictions](#network-and-firewall-restrictions) - [Enterprise Environment Scenarios](#enterprise-environment-scenarios) - [AADSTS500200 error: User account is a personal Microsoft account](#aadsts500200-error-user-account-is-a-personal-microsoft-account) + - [Using Azure Entra ID with Docker](#using-azure-entra-id-with-docker) ## Common Issues @@ -640,6 +641,59 @@ If you're behind a corporate firewall, you may need to: - Whitelist npm registry domains (`*.npmjs.org`, `registry.npmjs.org`) - Work with IT to ensure npm can download packages +### Using Azure Entra ID with Docker + +To use Azure Entra ID with the Docker image update the MCP client configuration to use `--volume` rather than `--env-file`. The value for `--volume` is a mapping from the host machine's `.azure` folder to the corresponding `.azure` directory in the container. + +1. On the host machine, log into Azure via Azure CLI. +2. Update MCP client configuration to point to the user's `.azure` folder. + ```json + { + "mcpServers": { + "Azure MCP Server": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "--volume", + "~/.azure:/root/.azure", + "mcr.microsoft.com/azure-sdk/azure-mcp:latest" + ] + } + } + } + ``` + +#### For Windows Users + +On Windows, Azure CLI stores credentials in an encrypted format that cannot be accessed from within Docker containers. On Linux and Mac, credentials are stored as plain JSON files that can be shared with containers. Consequently, mapping the `.azure` directory from the user profile to the container will not work on Windows. A workaround is to use WSL to log into the Azure CLI and then map that to the Docker container. There is an open issue to address this (https://github.com/Azure/azure-sdk-for-net/issues/19167). + +1. In a WSL console + ```bash + mkdir /mnt/c/users//.azure-wsl + AZURE_CONFIG_DIR=/mnt/c/users//.azure-wsl + az login + ``` +2. Update MCP client configuration to point that folder. + ```json + { + "mcpServers": { + "Azure MCP Server": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "--volume", + "C:\\users\\\\.azure-wsl:/root/.azure", + "mcr.microsoft.com/azure-sdk/azure-mcp:latest" + ] + } + } + } + ``` + ## Remote MCP Server ### SSE Transport