Reduce the size of the README (#332)

joshfree · JonathanCrd · web-flow · commit c682e81d8b05 · 2025-06-10T07:50:53.000-07:00
* Reduce the size of the README Refactor the README file move installation steps to the top merge duplicate content add collapsable sections for longer content * Add video tags Add video, width, height per GitHub docs on embedding a video in markdown * remove learn vsix extension reference remove sentence someone added about the learn vsix * Add "(Optional)" after most install types in the list Add "(Optional)" after most install types in the list * Clarify wording Co-authored-by: Jonathan Cárdenas <JonathanCrd@users.noreply.github.com> * Address feedback (#335) Address feedback * reorder sections reorder sections --------- Co-authored-by: Jonathan Cárdenas <JonathanCrd@users.noreply.github.com>
diff --git a/README.md b/README.md
@@ -1,24 +1,33 @@
 # 🌟 Azure MCP Server
 
+The Azure MCP Server implements the [MCP specification](https://modelcontextprotocol.io) to create a seamless connection between AI agents and Azure services.  Azure MCP Server can be used alone or with the [GitHub Copilot for Azure extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azure-github-copilot) in VS Code.  This project is in Public Preview and implementation may significantly change prior to our General Availability.
 
-[![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-Install_Azure_MCP_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=Azure%20MCP%20Server&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40azure%2Fmcp%40latest%22%2C%22server%22%2C%22start%22%5D%7D) [![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Azure_MCP_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=Azure%20MCP%20Server&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40azure%2Fmcp%40latest%22%2C%22server%22%2C%22start%22%5D%7D&quality=insiders)
-
-The Azure MCP Server implements the [MCP specification](https://modelcontextprotocol.io) to create a seamless connection between AI agents and key Azure services like Azure Storage, Cosmos DB, and more.
-
-> Please note that this project is in Public Preview and implementation may significantly change prior to our General Availability.
+Here's a short (16 seconds) video to help you get the Azure MCP Server installed in VS Code.
+<video src="https://github.com/user-attachments/assets/535f393c-0ed2-479d-9b24-5ca933293c92" width="1080" height="1920" controls></video>
 
-## 📑 Table of contents
-1. [🎯 Overview](#-overview)
-2. [🛠️ Currently Supported Tools](#%EF%B8%8F-currently-supported-tools)
-3. [🔌 Installation & Getting Started](#-getting-started)
-4. [🧪 Using Azure MCP Server](#-test-the-azure-mcp-server)
-5. [📝 Troubleshooting Issues](#-troubleshooting)
-6. [👥 Contributing to Azure MCP Server](#-contributing)
+### ⚙️ VS Code Install Steps (Recommended)
+1. Install either the stable or Insiders release of VS Code:
+   * [💫 Stable release](https://code.visualstudio.com/download)
+   * [🔮 Insiders release](https://code.visualstudio.com/insiders)
+2. Install the [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) and [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) extensions
+3. Install [Node.js](https://nodejs.org/en/download) 20 or later
+   * Ensure `node` and `npm` are in your path
+4. Open VS Code in an empty folder
+5. Install Azure MCP Server for either the stable or Insiders release of VS Code:
+   * [![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-Install_Azure_MCP_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=Azure%20MCP%20Server&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40azure%2Fmcp%40latest%22%2C%22server%22%2C%22start%22%5D%7D) 
+   * [![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Azure_MCP_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=Azure%20MCP%20Server&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40azure%2Fmcp%40latest%22%2C%22server%22%2C%22start%22%5D%7D&quality=insiders)
+6. Open GitHub Copilot in VS Code and [switch to Agent mode](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode)
+7. Click `refresh` on the tools list.
 
 
-## 🎯 Overview
+###  ▶️ Getting Started
+1. Open GitHub Copilot in VS Code and [switch to Agent mode](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode)
+2. You should see the Azure MCP Server in the list of tools
+3. Try a prompt that tells the agent to use the Azure MCP Server, such as "List my Azure Storage containers"
+4. The agent should be able to use the Azure MCP Server tools to complete your query
+5. For help with common issues see [Troubleshooting guide](https://github.com/Azure/azure-mcp/blob/main/TROUBLESHOOTING.md).
 
-### ✨ What can you do with the Azure MCP Server?
+## ✨ What can you do with the Azure MCP Server?
 
 The Azure MCP Server supercharges your agents with Azure context. Here are some cool prompts you can try:
 
@@ -48,18 +57,10 @@ The Azure MCP Server supercharges your agents with Azure context. Here are some
 - "List my Azure CDN endpoints"
 - "Help me build an Azure application using Node.js"
 
-### 🔍 How It Works
-
-The Azure MCP Server creates a seamless integration between AI agents and Azure services through:
-
-- 🔄 Smart JSON communication that AI agents understand
-- 🏗️ Natural language commands that get translated to Azure operations
-- 💡 Intelligent parameter suggestions and auto-completion
-- ⚡ Consistent error handling that makes sense
 
 ## 🛠️ Currently Supported Tools
-
-The Azure MCP Server provides tools for interacting with the following Azure services:
+<details>
+<summary>The Azure MCP Server provides tools for interacting with the following Azure services</summary>
 
 ### 🔎 Azure AI Search (search engine/vector database)
 - List Azure AI Search services
@@ -130,68 +131,39 @@ Agents and models can discover and learn best practices and usage guidelines for
 
 ### 🛡️ Azure Best Practices
 - Get secure, production-grade Azure SDK best practices for effective code generation.
+</details>
 
 For detailed command documentation and examples, see [Azure MCP Commands](https://github.com/Azure/azure-mcp/blob/main/docs/azmcp-commands.md).
 
-## 🔌 Getting Started
-
-The Azure MCP Server requires Node.js to install and run the server. If you don't have it installed, follow the instructions [here](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
-
-### VS Code + GitHub Copilot
-
-The Azure MCP Server provides Azure SDK and Azure CLI developer tools. It can be used alone or with the [GitHub Copilot for Azure extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azure-github-copilot) in VS Code. If you're interested in broad developer support across a variety of Azure development scenarios not included in the Azure MCP Server, such as searching documentation on Microsoft Learn, we recommend this extension as well.
-
-### Prerequisites
-1. Install either the stable or Insiders release of VS Code:
-   * [💫 Stable release](https://code.visualstudio.com/download)
-   * [🔮 Insiders release](https://code.visualstudio.com/insiders)
-2. Install the [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) and [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) extensions
-3. Install [Node.js](https://nodejs.org/en/download) 20 or later
-   * Ensure `node` and `npm` are in your path
-4. Open VS Code in an empty folder
-
-### Installation
+## 🔄️ Upgrading Existing Installs to the Latest Version
 
-#### ▶️ Getting Started Video
+<details>
+<summary>How to stay current with releases of Azure MCP Server</summary>
+    
+#### NPX
 
-Here's a short (16 seconds) video to help you get the Azure MCP Server installed in VS Code.
+If you use the default package spec of `@azure/mcp@latest`, npx will look for a new version on each server start. If you use just `@azure/mcp`, npx will continue to use its cached version until its cache is cleared.
 
-https://github.com/user-attachments/assets/535f393c-0ed2-479d-9b24-5ca933293c92
+#### NPM
 
-#### ✨ Quick install with VS Code
+If you globally install the cli via `npm install -g @azure/mcp` it will use the installed version until you manually update it with `npm update -g @azure/mcp`.
 
-Click one of these buttons to install the Azure MCP Server for VS Code or VS Code Insiders.
+#### Docker
 
-[![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-Install_Azure_MCP_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=Azure%20MCP%20Server&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40azure%2Fmcp%40latest%22%2C%22server%22%2C%22start%22%5D%7D) [![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Azure_MCP_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=Azure%20MCP%20Server&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40azure%2Fmcp%40latest%22%2C%22server%22%2C%22start%22%5D%7D&quality=insiders)
+There is no version update built into the docker image.  To update, just pull the latest from the repo and repeat the [docker installation instructions](#docker-install).
 
-You might get prompted to open the link with VS Code and then select "Install Server".
+#### VS Code
 
-Once you've installed the Azure MCP Server, make sure you select GitHub Copilot Agent Mode and refresh the tools list. To learn more about Agent Mode, visit the [VS Code Documentation](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode).
+Installation in VS Code should be in one of the previous forms and the update instructions are the same. If you installed the mcp server with the `npx` command and  `-y @azure/mcp@latest` args, npx will check for package updates each time VS Code starts the server. Using a docker container in VS Code has the same no-update limitation described above.
+</details>
 
-#### 🔧 Manual Install
+## ⚙️ Advanced Install Scenarios (Optional)
+<details>
+<summary>Docker containers, custom MCP clients, and manual install options</summary>
 
-For a step-by-step installation, follow these instructions:
+#### 🐋 Docker Install Steps (Optional)
+For a step-by-step Docker installation, follow these instructions:
 
-1. Add `.vscode/mcp.json`:
-```json
-{
-  "servers": {
-    "Azure MCP Server": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@azure/mcp@latest",
-        "server",
-        "start"
-      ]
-    }
-  }
-}
-```
-
-#### 🐋 Docker Install
-
-For a step-by-step installation, follow these instructions:
 1. Clone repository
 2. From repository root, build Docker image: `docker build -t azure/azuremcp .`
 3. Create an `.env` file with environment variables that [match one of the `EnvironmentCredential`](https://learn.microsoft.com/dotnet/api/azure.identity.environmentcredential) sets.  For example, a `.env` file using a service principal could look like:
@@ -221,34 +193,28 @@ AZURE_CLIENT_SECRET={YOUR_AZURE_CLIENT_SECRET}
 
 Optionally, customers can use `--env` or `--volume` to pass authentication values.
 
-### 🔄️ Updates
-
-#### NPX
-
-If you use the default package spec of `@azure/mcp@latest`, npx will look for a new version on each server start. If you use just `@azure/mcp`, npx will continue to use its cached version until its cache is cleared.
-
-#### NPM
-
-If you globally install the cli via `npm install -g @azure/mcp` it will use the installed version until you manually update it with `npm update -g @azure/mcp`.
-
-#### Docker
-
-There is no version update built into the docker image.  To update, just pull the latest from the repo and repeat the [docker installation instructions](#docker-install).
-
-#### VS Code
-
-Installation in VS Code should be in one of the previous forms and the update instructions are the same. If you installed the mcp server with the `npx` command and  `-y @azure/mcp@latest` args, npx will check for package updates each time VS Code starts the server. Using a docker container in VS Code has the same no-update limitation described above.
-
-## 🧪 Test the Azure MCP Server
-
-1. Open GitHub Copilot in VS Code and [switch to Agent mode](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode)
-2. You should see the Azure MCP Server in the list of tools
-3. Try a prompt that tells the agent to use the Azure MCP Server, such as "List my Azure Storage containers"
-4. The agent should be able to use the Azure MCP Server tools to complete your query
+#### 🤖 Custom MCP Client Install Steps (Optional)
+You can easily configure your MCP client to use the Azure MCP Server. Have your client run the following command and access it via standard IO or SSE.
 
-## 🤖 Custom MCP Clients
+#### 🔧 Manual Install Steps (Optional)
+For a step-by-step installation, follow these instructions:
 
-You can easily configure your MCP client to use the Azure MCP Server. Have your client run the following command and access it via standard IO or SSE.
+1. Add `.vscode/mcp.json`:
+```json
+{
+  "servers": {
+    "Azure MCP Server": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@azure/mcp@latest",
+        "server",
+        "start"
+      ]
+    }
+  }
+}
+```
 
 ### Using standard IO
 
@@ -272,12 +238,18 @@ Configure the MCP client to execute: `npx -y @azure/mcp@latest server start`. Fo
 
 
 More end-to-end MCP client/agent guides are coming soon!
+</details>
+
+
 
 ## 📝 Troubleshooting
 
 See [Troubleshooting guide](https://github.com/Azure/azure-mcp/blob/main/TROUBLESHOOTING.md) for help with common issues and logging.
 
-## 🔑 Authentication
+### 🔑 Authentication
+
+<details>
+<summary>We use Azure Identity SDK under the hood via DefaultAzureCredential, which tries these credentials in order:</summary>
 
 The Azure MCP Server seamlessly integrates with your host operating system's authentication mechanisms, making it super easy to get started! We use Azure Identity under the hood via [`DefaultAzureCredential`](https://learn.microsoft.com/dotnet/azure/sdk/authentication/credential-chains?tabs=dac), which tries these credentials in order:
 
@@ -302,6 +274,7 @@ AZURE_MCP_INCLUDE_PRODUCTION_CREDENTIALS=true
 ```
 
 This is useful when running on Azure services where you want to use managed identities.
+</details>
 
 ## 🛡️ Security Note
 
@@ -310,7 +283,6 @@ Your credentials are always handled securely through the official [Azure Identit
 MCP as a phenomenon is very novel and cutting-edge. As with all new technology standards, consider doing a security review to ensure any systems that integrate with MCP servers follow all regulations and standards your system is expected to adhere to. This includes not only the Azure MCP Server, but any MCP client/agent that you choose to implement down to the model provider.
 
 ## 👥 Contributing
-
 We welcome contributions to the Azure MCP Server! Whether you're fixing bugs, adding new features, or improving documentation, your contributions are welcome.
 
 Please read our [Contributing Guide](https://github.com/Azure/azure-mcp/blob/main/CONTRIBUTING.md) for guidelines on:
