From e1f482e21035461ca9bd5b4519d6c3c89b3be645 Mon Sep 17 00:00:00 2001 From: Josh Free Date: Fri, 26 Sep 2025 11:52:37 -0700 Subject: [PATCH 01/10] Fix Docker instructions, Add Manual IDE Setup Fix Docker instructions, Add Manual IDE Setup --- servers/Azure.Mcp.Server/README.md | 91 +++++++++++++++--------------- 1 file changed, 47 insertions(+), 44 deletions(-) diff --git a/servers/Azure.Mcp.Server/README.md b/servers/Azure.Mcp.Server/README.md index 9e514ad800..5eee4a8f41 100644 --- a/servers/Azure.Mcp.Server/README.md +++ b/servers/Azure.Mcp.Server/README.md @@ -12,7 +12,7 @@ All Azure MCP tools in a single server. The Azure MCP Server implements the [MCP - [VS Code (Recommended)](#vs-code-recommended) - [Visual Studio 2022](#visual-studio-2022) - [IntelliJ IDEA](#intellij-idea) - - [Additional IDEs](#additional-ides) + - [Manual IDE Setup](#manual-ide-setup) - [Package Manager](#package-manager) - [NuGet](#nuget) - [NPM](#npm) @@ -26,7 +26,7 @@ All Azure MCP tools in a single server. The Azure MCP Server implements the [MCP - [Feedback and Support](#feedback-and-support) - [Security](#security) - [Data Collection](#data-collection) - - [Contributing & Code of Conduct](#contributing) + - [Contributing and Code of Conduct](#contributing) # Overview @@ -62,41 +62,48 @@ From within Visual Studio 2022 install [GitHub Copilot for Azure (VS 2022)](http 1. Install the [GitHub Copilot](https://plugins.jetbrains.com/plugin/17718-github-copilot) plugin. 1. Install the [Azure Toolkit for Intellij](https://plugins.jetbrains.com/plugin/8053-azure-toolkit-for-intellij) plugin. -### Additional IDEs - -For IDEs not listed above, manually setup Azure MCP Server within the IDE. +### Manual IDE Setup +For manual configuration across different IDEs, setup Azure MCP Server within your IDE:
Manual setup instructions -Configure via `mcp.json` (VS Code example - adapt structure for your IDE): +#### Sample Configuration +Copy this configuration to your IDE's MCP configuration file: ```json - { - "servers": { - "Azure MCP Server": { - "command": "npx", - "args": [ +{ + "mcpServers": { + "azure-mcp-server": { + "command": "npx", + "args": [ "-y", "@azure/mcp@latest", "server", "start" - ] + ] } - } } +} ``` - -In some environments you may need to run the server directly: - -```bash - npx -y @azure/mcp@latest server start -``` - +**Note:** When manually configuring Visual Studio and Visual Studio Code, use `servers` instead of `mcpServers` as the root object. + +**IDE-Specific Configuration** +| IDE | File Location | Documentation Link | +|-----|---------------|-------------------| +| **Amazon Q Developer** | `~/.aws/amazonq/mcp.json` (global)
`.amazonq/mcp.json` (workspace) | [AWS Q Developer MCP Guide](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/qdev-mcp.html) | +| **Claude Code** | `~/.claude.json` or `.mcp.json` (project) | [Claude Code MCP Configuration](https://scottspence.com/posts/configuring-mcp-tools-in-claude-code) | +| **Claude Desktop** | `~/.claude/claude_desktop_config.json` (macOS)
`%APPDATA%\Claude\claude_desktop_config.json` (Windows) | [Claude Desktop MCP Setup](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop) | +| **Cursor** | `~/.cursor/mcp.json` or `.cursor/mcp.json` | [Cursor MCP Documentation](https://docs.cursor.com/context/model-context-protocol) | +| **IntelliJ IDEA** | Built-in MCP server (2025.2+)
Settings > Tools > MCP Server | [IntelliJ MCP Documentation](https://www.jetbrains.com/help/ai-assistant/mcp.html) | +| **Visual Studio** | `.mcp.json` (solution/workspace) | [Visual Studio MCP Setup](https://learn.microsoft.com/en-us/visualstudio/ide/mcp-servers?view=vs-2022) | +| **VS Code** | `.vscode/mcp.json` (workspace)
`settings.json` (user) | [VS Code MCP Documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) | +| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | [Windsurf Cascade MCP Integration](https://docs.windsurf.com/windsurf/cascade/mcp) |
## Package Manager +Package manager installation offers several advantages over IDE-specific setup, including centralized dependency management, CI/CD integration, support for headless/server environments, version control, and project portability. Install Azure MCP Server via a package manager: @@ -118,40 +125,36 @@ npm install -g @azure/mcp ### Docker -Microsoft publishes an official Azure MCP Server Docker container on the [Microsoft Artifact Registry](https://mcr.microsoft.com/artifact/mar/azure-sdk/azure-mcp). +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 +```
-Docker setup instructions +Docker instructions + +#### Create an env file with Azure credentials 1. Create a `.env` file with Azure credentials ([see EnvironmentCredential options](https://learn.microsoft.com/dotnet/api/azure.identity.environmentcredential)): ```bash - AZURE_TENANT_ID={YOUR_AZURE_TENANT_ID} - AZURE_CLIENT_ID={YOUR_AZURE_CLIENT_ID} - AZURE_CLIENT_SECRET={YOUR_AZURE_CLIENT_SECRET} +AZURE_TENANT_ID={YOUR_AZURE_TENANT_ID} +AZURE_CLIENT_ID={YOUR_AZURE_CLIENT_ID} +AZURE_CLIENT_SECRET={YOUR_AZURE_CLIENT_SECRET} ``` -2. Configure your MCP client with the Docker command: +#### Run with environment variables -```json - { - "servers": { - "Azure MCP Server": { - "command": "docker", - "args": [ - "run", - "-i", - "--rm", - "--env-file", - "/full/path/to/.env", - "mcr.microsoft.com/azure-sdk/azure-mcp:latest" - ] - } - } - } +2. Run using the `.env` file from step 1. Replace `/full/path/to/your.env` with the actual `.env` file path: + +```bash +docker run -i --rm --env-file /full/path/to/your.env \ + mcr.microsoft.com/azure-sdk/azure-mcp ``` - -Replace `/full/path/to/.env` with your actual .env file path. Alternatively, use individual `--env` flags or `--volume` mounts for credentials. + +Alternatively, use individual `--env` flags or `--volume` mounts for credentials. +
# Usage From fbad73ea749c51e86dee7372cd01e5eb7f26e6a2 Mon Sep 17 00:00:00 2001 From: Josh Free Date: Fri, 26 Sep 2025 11:59:07 -0700 Subject: [PATCH 02/10] Update servers/Azure.Mcp.Server/README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- servers/Azure.Mcp.Server/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/servers/Azure.Mcp.Server/README.md b/servers/Azure.Mcp.Server/README.md index 5eee4a8f41..71a7c23b18 100644 --- a/servers/Azure.Mcp.Server/README.md +++ b/servers/Azure.Mcp.Server/README.md @@ -63,7 +63,7 @@ From within Visual Studio 2022 install [GitHub Copilot for Azure (VS 2022)](http 1. Install the [Azure Toolkit for Intellij](https://plugins.jetbrains.com/plugin/8053-azure-toolkit-for-intellij) plugin. ### Manual IDE Setup -For manual configuration across different IDEs, setup Azure MCP Server within your IDE: +For manual configuration across different IDEs, set up Azure MCP Server within your IDE:
Manual setup instructions From 73e6eeea4dd7e5c9c16a87b391354f8ae050d459 Mon Sep 17 00:00:00 2001 From: Josh Free Date: Fri, 26 Sep 2025 12:14:53 -0700 Subject: [PATCH 03/10] Revise Docker run instructions in README.md Updated instructions for running the Azure MCP Server with Docker, replacing the bash command with a JSON configuration format. --- servers/Azure.Mcp.Server/README.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/servers/Azure.Mcp.Server/README.md b/servers/Azure.Mcp.Server/README.md index 71a7c23b18..11c1c1de9c 100644 --- a/servers/Azure.Mcp.Server/README.md +++ b/servers/Azure.Mcp.Server/README.md @@ -144,13 +144,26 @@ AZURE_CLIENT_ID={YOUR_AZURE_CLIENT_ID} AZURE_CLIENT_SECRET={YOUR_AZURE_CLIENT_SECRET} ``` -#### Run with environment variables +#### Configure your MCP client to use Docker: 2. Run using the `.env` file from step 1. Replace `/full/path/to/your.env` with the actual `.env` file path: -```bash -docker run -i --rm --env-file /full/path/to/your.env \ - mcr.microsoft.com/azure-sdk/azure-mcp +```json + { + "servers": { + "Azure MCP Server": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "--env-file", + "/full/path/to/your.env", + "mcr.microsoft.com/azure-sdk/azure-mcp:latest" + ] + } + } + } ``` Alternatively, use individual `--env` flags or `--volume` mounts for credentials. From 417b2e08cf818ca3768462a37cba9e33e26e5e0a Mon Sep 17 00:00:00 2001 From: Josh Free Date: Fri, 26 Sep 2025 12:16:42 -0700 Subject: [PATCH 04/10] tweak docker mcp.json root node tweak docker mcp.json root node --- servers/Azure.Mcp.Server/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/servers/Azure.Mcp.Server/README.md b/servers/Azure.Mcp.Server/README.md index 11c1c1de9c..06e09ee075 100644 --- a/servers/Azure.Mcp.Server/README.md +++ b/servers/Azure.Mcp.Server/README.md @@ -150,7 +150,7 @@ AZURE_CLIENT_SECRET={YOUR_AZURE_CLIENT_SECRET} ```json { - "servers": { + "mcpServers": { "Azure MCP Server": { "command": "docker", "args": [ @@ -165,6 +165,7 @@ AZURE_CLIENT_SECRET={YOUR_AZURE_CLIENT_SECRET} } } ``` +**Note:** When manually configuring Visual Studio and Visual Studio Code, use `servers` instead of `mcpServers` as the root object. Alternatively, use individual `--env` flags or `--volume` mounts for credentials. From 5bdd193733f382ff62b414bd3f715804b991c25d Mon Sep 17 00:00:00 2001 From: Josh Free Date: Fri, 26 Sep 2025 12:19:12 -0700 Subject: [PATCH 05/10] Fix formatting in README for MCP client setup Updated instructions for running MCP client with .env file. --- servers/Azure.Mcp.Server/README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/servers/Azure.Mcp.Server/README.md b/servers/Azure.Mcp.Server/README.md index 06e09ee075..83ee9019b7 100644 --- a/servers/Azure.Mcp.Server/README.md +++ b/servers/Azure.Mcp.Server/README.md @@ -146,7 +146,7 @@ AZURE_CLIENT_SECRET={YOUR_AZURE_CLIENT_SECRET} #### Configure your MCP client to use Docker: -2. Run using the `.env` file from step 1. Replace `/full/path/to/your.env` with the actual `.env` file path: +2. Run using the `.env` file from step 1. Replace `/full/path/to/your.env` with the actual `.env` file path. ```json { @@ -167,8 +167,6 @@ AZURE_CLIENT_SECRET={YOUR_AZURE_CLIENT_SECRET} ``` **Note:** When manually configuring Visual Studio and Visual Studio Code, use `servers` instead of `mcpServers` as the root object. -Alternatively, use individual `--env` flags or `--volume` mounts for credentials. -
# Usage From 340f492ab47b39224d4e2815c04af461be3ae677 Mon Sep 17 00:00:00 2001 From: Josh Free Date: Fri, 26 Sep 2025 12:40:08 -0700 Subject: [PATCH 06/10] remove en-us from link --- servers/Azure.Mcp.Server/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/servers/Azure.Mcp.Server/README.md b/servers/Azure.Mcp.Server/README.md index 83ee9019b7..1abb728252 100644 --- a/servers/Azure.Mcp.Server/README.md +++ b/servers/Azure.Mcp.Server/README.md @@ -96,7 +96,7 @@ Copy this configuration to your IDE's MCP configuration file: | **Claude Desktop** | `~/.claude/claude_desktop_config.json` (macOS)
`%APPDATA%\Claude\claude_desktop_config.json` (Windows) | [Claude Desktop MCP Setup](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop) | | **Cursor** | `~/.cursor/mcp.json` or `.cursor/mcp.json` | [Cursor MCP Documentation](https://docs.cursor.com/context/model-context-protocol) | | **IntelliJ IDEA** | Built-in MCP server (2025.2+)
Settings > Tools > MCP Server | [IntelliJ MCP Documentation](https://www.jetbrains.com/help/ai-assistant/mcp.html) | -| **Visual Studio** | `.mcp.json` (solution/workspace) | [Visual Studio MCP Setup](https://learn.microsoft.com/en-us/visualstudio/ide/mcp-servers?view=vs-2022) | +| **Visual Studio** | `.mcp.json` (solution/workspace) | [Visual Studio MCP Setup](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022) | | **VS Code** | `.vscode/mcp.json` (workspace)
`settings.json` (user) | [VS Code MCP Documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) | | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | [Windsurf Cascade MCP Integration](https://docs.windsurf.com/windsurf/cascade/mcp) | From 9e3034fbcf298ecad83bdff16e14a2d72cf8feaa Mon Sep 17 00:00:00 2001 From: Josh Free Date: Fri, 26 Sep 2025 12:43:55 -0700 Subject: [PATCH 07/10] Revise MCP client configuration instructions Updated instructions for configuring MCP client to include mcp.json. --- servers/Azure.Mcp.Server/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/servers/Azure.Mcp.Server/README.md b/servers/Azure.Mcp.Server/README.md index 1abb728252..c0855c0091 100644 --- a/servers/Azure.Mcp.Server/README.md +++ b/servers/Azure.Mcp.Server/README.md @@ -146,7 +146,9 @@ AZURE_CLIENT_SECRET={YOUR_AZURE_CLIENT_SECRET} #### Configure your MCP client to use Docker: -2. Run using the `.env` file from step 1. Replace `/full/path/to/your.env` with the actual `.env` file path. +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. ```json { From e7569ba8bb60889974283fc7e5dfd13b2eafeac7 Mon Sep 17 00:00:00 2001 From: Josh Free Date: Fri, 26 Sep 2025 12:44:45 -0700 Subject: [PATCH 08/10] Update README with MCP client configuration details Clarified instructions for configuring MCP client with Docker. --- servers/Azure.Mcp.Server/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/servers/Azure.Mcp.Server/README.md b/servers/Azure.Mcp.Server/README.md index c0855c0091..9d88276927 100644 --- a/servers/Azure.Mcp.Server/README.md +++ b/servers/Azure.Mcp.Server/README.md @@ -146,9 +146,9 @@ AZURE_CLIENT_SECRET={YOUR_AZURE_CLIENT_SECRET} #### 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. +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. ```json { From dc3c8422f984ad5b270ca70cb314b12f685dcc88 Mon Sep 17 00:00:00 2001 From: Josh Free Date: Fri, 26 Sep 2025 12:45:58 -0700 Subject: [PATCH 09/10] Update README with configuration notes Clarify configuration instructions for Visual Studio and Visual Studio Code. --- servers/Azure.Mcp.Server/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/servers/Azure.Mcp.Server/README.md b/servers/Azure.Mcp.Server/README.md index 9d88276927..e4056aca03 100644 --- a/servers/Azure.Mcp.Server/README.md +++ b/servers/Azure.Mcp.Server/README.md @@ -149,6 +149,7 @@ AZURE_CLIENT_SECRET={YOUR_AZURE_CLIENT_SECRET} 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. ```json { @@ -167,7 +168,6 @@ AZURE_CLIENT_SECRET={YOUR_AZURE_CLIENT_SECRET} } } ``` -**Note:** When manually configuring Visual Studio and Visual Studio Code, use `servers` instead of `mcpServers` as the root object. From c8dda5079efd343037ebc6aa1ea637ad44944159 Mon Sep 17 00:00:00 2001 From: Josh Free Date: Fri, 26 Sep 2025 13:15:57 -0700 Subject: [PATCH 10/10] Rename 'Manual IDE Setup' to 'Manual Setup' Updated section titles and descriptions for clarity. --- servers/Azure.Mcp.Server/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/servers/Azure.Mcp.Server/README.md b/servers/Azure.Mcp.Server/README.md index e4056aca03..df6760ab40 100644 --- a/servers/Azure.Mcp.Server/README.md +++ b/servers/Azure.Mcp.Server/README.md @@ -12,7 +12,7 @@ All Azure MCP tools in a single server. The Azure MCP Server implements the [MCP - [VS Code (Recommended)](#vs-code-recommended) - [Visual Studio 2022](#visual-studio-2022) - [IntelliJ IDEA](#intellij-idea) - - [Manual IDE Setup](#manual-ide-setup) + - [Manual Setup](#manual-setup) - [Package Manager](#package-manager) - [NuGet](#nuget) - [NPM](#npm) @@ -62,15 +62,15 @@ From within Visual Studio 2022 install [GitHub Copilot for Azure (VS 2022)](http 1. Install the [GitHub Copilot](https://plugins.jetbrains.com/plugin/17718-github-copilot) plugin. 1. Install the [Azure Toolkit for Intellij](https://plugins.jetbrains.com/plugin/8053-azure-toolkit-for-intellij) plugin. -### Manual IDE Setup -For manual configuration across different IDEs, set up Azure MCP Server within your IDE: +### Manual Setup +Azure MCP Server can also be configured across other IDEs, CLIs, and MCP clients:
Manual setup instructions #### Sample Configuration -Copy this configuration to your IDE's MCP configuration file: +Copy this configuration to your client's MCP configuration file: ```json { "mcpServers": { @@ -88,7 +88,7 @@ Copy this configuration to your IDE's MCP configuration file: ``` **Note:** When manually configuring Visual Studio and Visual Studio Code, use `servers` instead of `mcpServers` as the root object. -**IDE-Specific Configuration** +**Client-Specific Configuration** | IDE | File Location | Documentation Link | |-----|---------------|-------------------| | **Amazon Q Developer** | `~/.aws/amazonq/mcp.json` (global)
`.amazonq/mcp.json` (workspace) | [AWS Q Developer MCP Guide](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/qdev-mcp.html) |