|
3 | 3 | This guide will help you get started with the Azure DevOps MCP Server in different environments. |
4 | 4 |
|
5 | 5 | - [Prerequisites](#-prerequisites) |
| 6 | +- [Authentication Methods](#-authentication-methods) |
6 | 7 | - [Getting started with Visual Studio Code & GitHub Copilot](#️-visual-studio-code--github-copilot) |
7 | 8 | - [Getting started with Visual Studio 2022 & GitHub Copilot](#%EF%B8%8F-visual-studio-2022--github-copilot) |
8 | 9 | - [Getting started with GitHub Copilot CLI](#-using-mcp-server-with-github-copilot-cli) |
@@ -30,18 +31,119 @@ Before you begin, make sure you have: |
30 | 31 | 1. Install [VS Studio 2022 version 17.14](https://learn.microsoft.com/en-us/visualstudio/releases/2022/release-history) or later |
31 | 32 | 2. Open a project in Visual Studio |
32 | 33 |
|
33 | | -## 🍕 Installation Options |
| 34 | +## 🔐 Authentication Methods |
34 | 35 |
|
35 | | -### ➡️ Visual Studio Code & GitHub Copilot |
| 36 | +The Azure DevOps MCP Server supports several authentication methods. Pass the desired method via the `--authentication` (`-a`) flag in your `mcp.json` configuration. |
36 | 37 |
|
37 | | -For the best experience, use Visual Studio Code and GitHub Copilot. |
| 38 | +| Method | Flag value | Environment variable | Best for | |
| 39 | +| ----------------------------- | ------------- | ----------------------- | ----------------------------------------------------- | |
| 40 | +| Interactive (default) | `interactive` | — | Local development, first-time setup | |
| 41 | +| Azure CLI | `azcli` | — | Workstations already signed in with `az login` | |
| 42 | +| Environment variable (bearer) | `envvar` | `ADO_MCP_AUTH_TOKEN` | CI/CD, automation | |
| 43 | +| Personal Access Token | `pat` | `PERSONAL_ACCESS_TOKEN` | CI/CD, service accounts, non-interactive environments | |
| 44 | + |
| 45 | +### 🔵 Interactive (Default) |
| 46 | + |
| 47 | +Opens a browser window for Microsoft account login. No extra configuration needed — this is the default when `--authentication` is omitted. |
| 48 | + |
| 49 | +```json |
| 50 | +{ |
| 51 | + "servers": { |
| 52 | + "ado": { |
| 53 | + "type": "stdio", |
| 54 | + "command": "npx", |
| 55 | + "args": ["-y", "@azure-devops/mcp", "<your-org>"] |
| 56 | + } |
| 57 | + } |
| 58 | +} |
| 59 | +``` |
| 60 | + |
| 61 | +### 🟢 Azure CLI (`azcli`) |
| 62 | + |
| 63 | +Uses the token from an active `az login` session. Requires the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) to be installed and signed in. |
| 64 | + |
| 65 | +```json |
| 66 | +{ |
| 67 | + "servers": { |
| 68 | + "ado": { |
| 69 | + "type": "stdio", |
| 70 | + "command": "npx", |
| 71 | + "args": ["-y", "@azure-devops/mcp", "<your-org>", "--authentication", "azcli"] |
| 72 | + } |
| 73 | + } |
| 74 | +} |
| 75 | +``` |
| 76 | + |
| 77 | +### 🟡 Environment Variable — Bearer Token (`envvar`) |
| 78 | + |
| 79 | +Reads a raw bearer token from the `ADO_MCP_AUTH_TOKEN` environment variable. Useful when another tool or pipeline injects the token at runtime. |
| 80 | + |
| 81 | +1. Set the environment variable: |
| 82 | + |
| 83 | + ```bash |
| 84 | + export ADO_MCP_AUTH_TOKEN="<your-azure-devops-bearer-token>" |
| 85 | + ``` |
| 86 | + |
| 87 | +2. Configure `.vscode/mcp.json`: |
| 88 | + |
| 89 | + ```json |
| 90 | + { |
| 91 | + "inputs": [ |
| 92 | + { |
| 93 | + "id": "ado_org", |
| 94 | + "type": "promptString", |
| 95 | + "description": "Azure DevOps organization name (e.g. 'contoso')" |
| 96 | + } |
| 97 | + ], |
| 98 | + "servers": { |
| 99 | + "ado": { |
| 100 | + "type": "stdio", |
| 101 | + "command": "npx", |
| 102 | + "args": ["-y", "@azure-devops/mcp", "${input:ado_org}", "--authentication", "envvar"] |
| 103 | + } |
| 104 | + } |
| 105 | + } |
| 106 | + ``` |
| 107 | + |
| 108 | +### 🔑 Personal Access Token (`pat`) |
38 | 109 |
|
39 | | -#### ✨ One-Click Install |
| 110 | +Authenticates using an Azure DevOps [Personal Access Token (PAT)](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate). The token must be stored in the `PERSONAL_ACCESS_TOKEN` environment variable as a **base64-encoded** string. |
40 | 111 |
|
41 | | -[](https://insiders.vscode.dev/redirect/mcp/install?name=ado&config=%7B%20%22type%22%3A%20%22stdio%22%2C%20%22command%22%3A%20%22npx%22%2C%20%22args%22%3A%20%5B%22-y%22%2C%20%22%40azure-devops%2Fmcp%22%2C%20%22%24%7Binput%3Aado_org%7D%22%5D%7D&inputs=%5B%7B%22id%22%3A%20%22ado_org%22%2C%20%22type%22%3A%20%22promptString%22%2C%20%22description%22%3A%20%22Azure%20DevOps%20organization%20name%20%20%28e.g.%20%27contoso%27%29%22%7D%5D) |
42 | | -[](https://insiders.vscode.dev/redirect/mcp/install?name=ado&quality=insiders&config=%7B%20%22type%22%3A%20%22stdio%22%2C%20%22command%22%3A%20%22npx%22%2C%20%22args%22%3A%20%5B%22-y%22%2C%20%22%40azure-devops%2Fmcp%22%2C%20%22%24%7Binput%3Aado_org%7D%22%5D%7D&inputs=%5B%7B%22id%22%3A%20%22ado_org%22%2C%20%22type%22%3A%20%22promptString%22%2C%20%22description%22%3A%20%22Azure%20DevOps%20organization%20name%20%20%28e.g.%20%27contoso%27%29%22%7D%5D) |
| 112 | +#### PAT format |
43 | 113 |
|
44 | | -After installation, select GitHub Copilot Agent Mode and refresh the tools list. Learn more about Agent Mode in the [VS Code Documentation](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode). |
| 114 | +The value stored in `PERSONAL_ACCESS_TOKEN` must be the base64 encoding of `<email>:<pat>`, where `<email>` is any non-empty string (the Azure DevOps API only uses the token portion) and `<pat>` is the raw PAT you copied from Azure DevOps. |
| 115 | + |
| 116 | +#### `.vscode/mcp.json` configuration |
| 117 | + |
| 118 | +```json |
| 119 | +{ |
| 120 | + "inputs": [ |
| 121 | + { |
| 122 | + "id": "ado_org", |
| 123 | + "type": "promptString", |
| 124 | + "description": "Azure DevOps organization name (e.g. 'contoso')" |
| 125 | + } |
| 126 | + ], |
| 127 | + "servers": { |
| 128 | + "ado": { |
| 129 | + "type": "stdio", |
| 130 | + "command": "npx", |
| 131 | + "args": ["-y", "@azure-devops/mcp", "${input:ado_org}", "--authentication", "pat"], |
| 132 | + "env": { |
| 133 | + "PERSONAL_ACCESS_TOKEN": "<base64encoded email:pat>" |
| 134 | + } |
| 135 | + } |
| 136 | + } |
| 137 | +} |
| 138 | +``` |
| 139 | + |
| 140 | +> **Security note:** Avoid hard-coding the PAT value directly in `mcp.json` when committing to source control. Prefer injecting it via an environment variable set outside the config file, or use a secrets manager. |
| 141 | +
|
| 142 | +## 🍕 Installation Options |
| 143 | + |
| 144 | +### ➡️ Visual Studio Code & GitHub Copilot |
| 145 | + |
| 146 | +For the best experience, use Visual Studio Code and GitHub Copilot. |
45 | 147 |
|
46 | 148 | #### 🧨 Install from Public Feed (Recommended) |
47 | 149 |
|
|
0 commit comments