You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/EXAMPLES.md
+12-10Lines changed: 12 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,17 +1,19 @@
1
+
# Azure DevOps MCP Server: Example Usage
2
+
1
3
This guide offers step-by-step examples for using the Azure DevOps MCP Server to interact with your Azure DevOps organization. For additional tips and best practices, see the [How To guide](./HOWTO.md).
2
4
3
5
> 📝 These examples have been tested and validated only in English. If you encounter issues when using a different language, please open an issue in the repository so we can investigate.
4
6
5
-
[Get List of Projects](#get-list-of-projects)<br/>
6
-
[Get List of Teams](#get-list-of-teams)<br/>
7
-
[Get My Work Items](#get-my-work-items)<br/>
8
-
[Get Work Items in a Backlog](#get-all-work-items-in-a-backlog)<br/>
9
-
[Retrieve and Edit Work Items](#retrieve-and-edit-work-items)<br/>
10
-
[Create and Link Test Cases](#create-and-link-test-cases)<br/>
Before you get started, ensure you follow the steps in the `README.md` file. This will help you get up and running and connected to your Azure DevOps organization.
2
4
3
-
###Does the MCP Server support both Azure DevOps Services and on-premises deployments?
5
+
## Does the MCP Server support both Azure DevOps Services and on-premises deployments?
4
6
5
7
Currently, the MCP Server supports only Azure DevOps Services. Several required API endpoints are not yet available for on-premises deployments. Additionally, focusing on Azure DevOps Services during the public preview makes it easier to debug and deliver fixes.
6
8
7
-
###Can I connect to more than one organization at a time?
9
+
## Can I connect to more than one organization at a time?
8
10
9
11
No, you can connect to only one organization at a time. However, you can switch organizations as needed.
10
12
11
-
###Can I set a default project instead of fetching the list every time?
13
+
## Can I set a default project instead of fetching the list every time?
12
14
13
15
Currently, you need to fetch the list of projects so the LLM has context about the project name or ID. We plan to improve this experience in the future by leveraging prompts. In the meantime, you can set a default project name in your `copilot-instructions.md` file.
In chat, switch to [Agent Mode](https://code.visualstudio.com/blogs/2025/02/24/introducing-copilot-agent-mode).
86
86
87
87
Click "Select Tools" and choose the available tools.
88
88
89
-
<imgsrc="../docs/media/configure-mcp-server-tools.gif"alt="configure mcp server tools"width="300"/>
89
+
90
90
91
91
> 💥 We strongly recommend creating a `.github\copilot-instructions.md` in your project and copying the contents from this [copilot-instructions.md](../.github/copilot-instructions.md) file. This will enhance your experience using the Azure DevOps MCP Server with GitHub Copilot Chat.
92
92
@@ -136,13 +136,13 @@ Edit or add `.vscode/mcp.json`:
In chat, switch to [Agent Mode](https://code.visualstudio.com/blogs/2025/02/24/introducing-copilot-agent-mode).
142
142
143
143
Click "Select Tools" and choose the available tools.
144
144
145
-
<imgsrc="../docs/media/configure-mcp-server-tools.gif"alt="configure mcp server tools"width="300"/>
145
+
146
146
147
147
> 💥 We strongly recommend creating a `.github\copilot-instructions.md` in your project and copying the contents from this [copilot-instructions.md](../.github/copilot-instructions.md) file. This will help you get the best experience using the Azure DevOps MCP Server in GitHub Copilot Chat.
148
148
@@ -183,13 +183,13 @@ Save the file.
183
183
184
184
Add your organization name by clicking on the `input` option.
185
185
186
-
<imgsrc="../docs/media/start-mcp-server-from-vs.png"alt="start mcp server from visual studio 2022"width="250"/>
186
+
187
187
188
188
Open Copilot chat and switch to [Agent Mode](https://learn.microsoft.com/en-us/visualstudio/ide/copilot-agent-mode?view=vs-2022).
189
189
190
190
Click the "Tools" icon and choose the available tools.
191
191
192
-
<imgsrc="../docs/media/set-tools-from-vs.png"alt="set tools to use in visual studio 2022"width="250"/>
192
+
193
193
194
194
> 💥 We strongly recommend creating a `.github\copilot-instructions.md` in your project and copying the contents from this [copilot-instructions.md](../.github/copilot-instructions.md) file. This will enhance your experience using the Azure DevOps MCP Server with GitHub Copilot Chat.
195
195
@@ -210,7 +210,7 @@ See https://docs.anthropic.com/en/docs/claude-code/mcp for general guidance on a
210
210
211
211
For the Azure DevOps MCP Server, use the following command:
212
212
213
-
```
213
+
```bash
214
214
claude mcp add azure-devops -- npx -y @azure-devops/mcp Contoso
215
215
```
216
216
@@ -235,13 +235,13 @@ Replace `{Contoso}` with your actual Azure DevOps organization name.
235
235
236
236
Save the file, and when Cursor detects the MCP Server, click **Enable**.
237
237
238
-
<imgsrc="../docs/media/enable-mcp-server-from-cursor.png"alt="enable mcp server from cursor"width="500"/>
238
+
Be sure to follow all the steps in the [Getting Started guide](./GETTINGSTARTED.md) to quickly set up and connect to your Azure DevOps organization.
2
-
3
1
# 🥇 How to make your experience better
4
2
5
-
### Modify Copilot Instructions
3
+
Be sure to follow all the steps in the [Getting Started guide](./GETTINGSTARTED.md) to quickly set up and connect to your Azure DevOps organization.
4
+
5
+
## Modify Copilot Instructions
6
6
7
7
The `.github/copilot-instructions.md` file is a great way to customize the GitHub Copilot experience, especially when working with MCP Server for Azure DevOps.
8
8
9
9
From the [GitHub documentation](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot):
10
10
11
11
> Instead of repeatedly adding this contextual detail to your chat questions, you can create a file in your repository that automatically adds this information for you. The additional information is not displayed in the chat but is available to Copilot to allow it to generate higher-quality responses.
12
12
13
-
####Example Modification
13
+
## Example Modification
14
14
15
15
Here is an example modification you can add to your existing `.github/copilot-instructions.md` file.
16
16
@@ -20,6 +20,6 @@ Here is an example modification you can add to your existing `.github/copilot-in
20
20
When getting work items using MCP Server for Azure DevOps, always try to use batch tools for updates instead of many individual single updates. For updates, try and update up to 200 updates in a single batch. When getting work items, once you get the list of IDs, use the tool `get_work_items_batch_by_ids` to get the work item details. By default, show fields ID, Type, Title, State. Show work item results in a rendered markdown table.
21
21
```
22
22
23
-
###Use different models
23
+
## Use different models
24
24
25
25
Communicating with the LLM is both an art and a science. If the model does not respond well, switching to a different model may improve your results.
Copy file name to clipboardExpand all lines: docs/TROUBLESHOOTING.md
+8-3Lines changed: 8 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,17 +30,22 @@
30
30
1.**npm Authentication Issues for Remote Access**
31
31
If you encounter authentication errors:
32
32
- Ensure you are logged in to Azure DevOps using the `az` CLI:
33
+
33
34
```pwsh
34
35
az login
35
36
```
37
+
36
38
- Verify your npm configuration:
39
+
37
40
```pwsh
38
41
npm config get registry
39
42
```
43
+
40
44
It should point to: `https://registry.npmjs.org/`
41
45
42
46
2. **Dependency Installation Errors**
43
47
If `npm install` fails, verify that you are using Node.js version 20 or higher. You can check your Node.js version with:
48
+
44
49
```pwsh
45
50
node -v
46
51
```
@@ -135,22 +140,22 @@ The MCP server may be authenticating with a different tenant than your Azure Dev
135
140
136
141
If the tenant configuration solution above doesn't resolve your authentication issues, and you're working in a **Dev Container** or **WSL (Windows Subsystem for Linux)** environment, the root cause may be different.
137
142
138
-
#### Symptoms
143
+
#### Dev Container/WSL Symptoms
139
144
140
145
- Same authorization errors as above (`TF400813: The user 'xxx' is not authorized to access this resource`)
141
146
- Tenant ID configuration didn't resolve the issue
142
147
- You're using VS Code with Dev Containers or WSL
143
148
- MCP server is configured in User Settings (global) rather than workspace settings
144
149
145
-
#### Root Cause
150
+
#### Dev Container/WSL Root Cause
146
151
147
152
When MCP servers are configured in **User Settings** (global configuration), they inherit the environment context from the **host machine**, including `az login` authentication settings. In Dev Container or WSL scenarios, this means:
148
153
149
154
- The MCP server uses the host machine's Azure authentication
150
155
- Any `az login` performed inside the Dev Container or WSL environment is ignored
151
156
- There may be a mismatch between the authentication context the MCP server expects and your development environment
152
157
153
-
#### Solution
158
+
#### Dev Container/WSL Solution
154
159
155
160
1.**Verify your MCP configuration location**:
156
161
- Check if your MCP server is configured in User Settings (global) vs Workspace Settings
0 commit comments