Configure the Azure DevOps MCP
This guide explains, step by step, how to connect Azure DevOps (Azure Boards) so that NEO reads user stories directly from work items, without you having to copy them into a file.
| Server name | azure-devops (always use this name) |
| Package | @tiberriver256/mcp-server-azure-devops, run with npx -y |
| Type | Local (stdio): it runs on your computer |
| Supported instance | Azure DevOps Services (https://dev.azure.com/<organization> or https://<organization>.visualstudio.com) |
| Access | Read-only: NEO never modifies work items |
| Skills that use it | lippia-neo-fetch-user-story, and through it lippia-neo-read-user-story and lippia-neo-resolve-user-story-source when you give them an Azure DevOps link |
1. What does NEO do with Azure DevOps?
When you give the assistant an ID (1234) or an Azure Boards link (https://dev.azure.com/techstore/Web/_workitems/edit/1234):
lippia-neo-resolve-user-story-sourcerecognizes that it's an Azure DevOps work item and checks that the link belongs to your configured organization.lippia-neo-fetch-user-storyfetches the work item with all its fields through theazure-devopsserver.- It converts the description from HTML to markdown as is, without reordering or summarizing. For Bugs, if the description is empty, it uses the Repro Steps.
- It returns the story in memory, in the same format as a local story. It doesn't write any file.
lippia-neo-read-user-storyreads it and continues the normal QA flow.
NEOonly reads. It doesn't comment, change states, edit, or create work items. That's why the recommended token has only the Work Items → Read permission.
2. Before you start
| You need | Why | How to check it |
|---|---|---|
Node.js (includes npx) |
The server is launched with npx. Without npx, it never starts |
node -v · npx --version |
| An Azure DevOps user with access to the project | The server sees exactly what your user sees | Being able to open the work item in the browser |
| Your organization's URL | It goes in AZURE_DEVOPS_ORG_URL |
It's the URL you use to sign in, up to the organization name (https://dev.azure.com/techstore) |
If you don't have Node.js, install the LTS version from nodejs.org. Then open a new terminal and restart the assistant so that npx is in the PATH.
3. Step 1 — Create the Personal Access Token (PAT)
The server doesn't use your password: it uses a Personal Access Token.
- Sign in to Azure DevOps and open User settings (your user icon, top right) → Personal access tokens. Or go straight to
https://dev.azure.com/<your-organization>/_usersSettings/tokens. - Click New Token.
- Fill in:
| Field | What to enter |
|---|---|
| Name | Something that identifies it, for example NEO - QA |
| Organization | The organization where the work items are |
| Expiration | Whatever your company's policy allows. Write down the date: when it expires, the connection stops working |
| Scopes | Custom defined → Work Items → Read. Nothing else |
- Click Create and copy the token right away: you can't see it again later.
- Store it somewhere safe, for example a password manager. Never paste it into a file that gets pushed to git.
4. Step 2 — Tell qa-stack.yaml that your stories come from Azure DevOps
paths:
user_stories_storage:
type: cloud
cloud_provider_mcp: azure-devops
local_path: user-stories/ # stays at the default: work items are never saved here
# Optional: Azure DevOps reading settings
azure_devops:
acceptance_criteria_field: Microsoft.VSTS.Common.AcceptanceCriteria # standard Azure Boards field
default_project: Web # default Team Project (optional)
| Field | What it's for | Default value |
|---|---|---|
user_stories_storage.type: cloud + cloud_provider_mcp: azure-devops |
Tells NEO that your stories come from Azure DevOps. Without this, Azure links are rejected |
— |
azure_devops.acceptance_criteria_field |
The field the acceptance criteria are taken from | Microsoft.VSTS.Common.AcceptanceCriteria |
azure_devops.default_project |
The project used if it isn't in the link or in your request | — |
lippia-neo-bootstrap-stackasks you all of this if you choose "stories in Azure DevOps", and it also builds.mcp.jsonfor you (Step 3).
Where are the acceptance criteria?
NEO looks for them in this order and uses the first one it finds:
| Order | Where it looks |
|---|---|
| 1 | The field configured in azure_devops.acceptance_criteria_field (by default, the Azure Boards Acceptance Criteria field) |
| 2 | The work item description: a "Criterios de aceptación" / "Acceptance Criteria" / "AC" heading, a list, or Gherkin blocks (Dado/Cuando/Entonces) |
| 3 | If it doesn't find anything, it doesn't make them up: it leaves a note so you can fill them in by hand |
If your team writes the criteria in the description and leaves the Acceptance Criteria field empty, set
acceptance_criteria_field: null.
Which project does it fetch the work item from?
In this order: the project you mention in your request → azure_devops.default_project in qa-stack.yaml → AZURE_DEVOPS_DEFAULT_PROJECT in .mcp.json. If the link contains a project different from the configured one, NEO uses the one in the link and lets you know.
5. Step 3 — Configure the server in your assistant
Base for everyone: .mcp.json in the project root
{
"mcpServers": {
"azure-devops": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
"env": {
"AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/techstore",
"AZURE_DEVOPS_AUTH_METHOD": "pat",
"AZURE_DEVOPS_PAT": "<your PAT>",
"AZURE_DEVOPS_DEFAULT_PROJECT": "Web"
}
}
}
}
| Key | Required? | What it's for |
|---|---|---|
AZURE_DEVOPS_ORG_URL |
Yes | The organization's URL |
AZURE_DEVOPS_AUTH_METHOD |
Yes, with the value "pat" |
If you don't set it, the server uses a different method (azure-identity) and ignores your PAT |
AZURE_DEVOPS_PAT |
Yes | The token from Step 1 |
AZURE_DEVOPS_DEFAULT_PROJECT |
No | Default project |
⚠️ Keep this
.mcp.jsoneven if you use a different assistant. TheNEOskills readAZURE_DEVOPS_ORG_URLfrom.mcp.jsonfor two things: to check that the link you give belongs to your organization, and to build the link back to the work item in the report. If you use Copilot, Codex, or Claude Desktop (which store their configuration in a different file) and there's no.mcp.jsonwithAZURE_DEVOPS_ORG_URL,lippia-neo-resolve-user-story-sourceconsiders Azure DevOps not configured and stops with "URL de Azure DevOps pero el proyecto no está configurado para ese proveedor" ("Azure DevOps URL, but the project isn't configured for that provider").
.mcp.json must be in .gitignore: it contains the token. What gets versioned is .mcp.json.template.
Depending on your assistant
| Assistant | What to do | Format details |
|---|---|---|
| Claude Code (VS Code, CLI, or the Code tab of Claude Desktop) | Nothing else: it reads the .mcp.json above. Reload the window or open a new session and approve the server |
IDE |
| GitHub Copilot in VS Code | Add the server to .vscode/mcp.json with the servers key, and use inputs for the token |
IDE |
| GitHub Copilot in JetBrains / Visual Studio | Same content with the servers key |
JetBrains · Visual Studio |
| Codex (extension, CLI, or ChatGPT app) | A [mcp_servers.azure-devops] section in ~/.codex/config.toml |
IDE · Terminal |
| Cursor | Copy the block as is into .cursor/mcp.json |
IDE |
| Claude Desktop (chat) | Copy the block, without type, into claude_desktop_config.json and restart the app |
Desktop |
| ChatGPT (regular chat) | ❌ It doesn't work: it only accepts remote servers. Use Codex | Desktop |
Example for Copilot in VS Code (.vscode/mcp.json):
{
"inputs": [
{ "id": "azure-pat", "type": "promptString", "description": "PAT de Azure DevOps", "password": true }
],
"servers": {
"azure-devops": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@tiberriver256/mcp-server-azure-devops"],
"env": {
"AZURE_DEVOPS_ORG_URL": "https://dev.azure.com/techstore",
"AZURE_DEVOPS_AUTH_METHOD": "pat",
"AZURE_DEVOPS_PAT": "${input:azure-pat}",
"AZURE_DEVOPS_DEFAULT_PROJECT": "Web"
}
}
}
}
Example for Codex (~/.codex/config.toml):
[mcp_servers.azure-devops]
command = "npx"
args = ["-y", "@tiberriver256/mcp-server-azure-devops"]
[mcp_servers.azure-devops.env]
AZURE_DEVOPS_ORG_URL = "https://dev.azure.com/techstore"
AZURE_DEVOPS_AUTH_METHOD = "pat"
AZURE_DEVOPS_PAT = "<your PAT>"
AZURE_DEVOPS_DEFAULT_PROJECT = "Web"
With a command, in Claude Code CLI:
claude mcp add --transport stdio --scope project \
--env AZURE_DEVOPS_ORG_URL=https://dev.azure.com/techstore \
--env AZURE_DEVOPS_AUTH_METHOD=pat \
--env AZURE_DEVOPS_PAT=<your PAT> \
--env AZURE_DEVOPS_DEFAULT_PROJECT=Web \
azure-devops -- npx -y @tiberriver256/mcp-server-azure-devops
Other authentication methods: the server also accepts
azure-cli(it uses youraz loginsession) andazure-identity(Azure credentials).NEOis documented and tested withpat.What about Microsoft's official MCP? Microsoft publishes its own Azure DevOps MCP server.
NEOuses@tiberriver256/mcp-server-azure-devopsbecause it's the one in its template. Don't load both under the same name.
6. Links with the visualstudio.com domain
Azure DevOps has two domains for the same organization:
| Domain | Example |
|---|---|
| Current | https://dev.azure.com/techstore/Web/_workitems/edit/1234 |
| Legacy | https://techstore.visualstudio.com/Web/_workitems/edit/1234 |
NEO recognizes both, but it compares the link's domain with the one in AZURE_DEVOPS_ORG_URL. If your team shares *.visualstudio.com links and you configured https://dev.azure.com/techstore (or the other way around), validation rejects them. You have two options:
- Give
NEOthe work item ID (1234) instead of the link. - Use the same domain your team's links use in
AZURE_DEVOPS_ORG_URL.
7. Check that it works
- Restart the assistant (or reload the window). Servers are read at startup.
- Open the server list (
/mcpin Claude Code or Codex, MCP: List Servers in VS Code…) and confirm thatazure-devopsshows as connected. - Try it with a real work item:
/lippia-neo-fetch-user-story https://dev.azure.com/techstore/Web/_workitems/edit/1234
It should return the work item's title, type, state, description, and acceptance criteria, indicating which field they came from.
8. Common problems (and what to do)
| What you see | Why it can happen | What to do |
|---|---|---|
❌ Azure DevOps MCP no está disponible en este entorno |
The azure-devops server isn't configured or didn't start |
Review Step 3 and restart the assistant |
The azure-devops server shows as Failed |
Node.js is missing, or the assistant can't find npx in the PATH |
Install Node.js, open a new terminal, and restart the assistant |
| Authentication error even though the PAT is correct | AZURE_DEVOPS_AUTH_METHOD: "pat" is missing |
Add it |
| 401 / unauthorized error | The PAT expired, was created for another organization, or doesn't have the Work Items → Read permission | Create a new PAT for that organization with that permission |
| The work item "doesn't exist" | Your user doesn't have permission on that project, the ID belongs to another project, or the ID is wrong | Open the work item in the browser with your user, or specify the correct project |
🛑 URL de Azure DevOps pero el proyecto no está configurado para ese proveedor |
cloud_provider_mcp: azure-devops is missing from qa-stack.yaml, or there's no azure-devops server in .mcp.json |
Complete Step 2 and the base .mcp.json from Step 3 |
🛑 La URL apunta a una instancia de Azure DevOps distinta a la configurada |
The link belongs to another organization, or uses the other domain (visualstudio.com vs. dev.azure.com) |
See section 6 |
No pude resolver el ID del work item |
The reference doesn't contain a work item number | Give the ID or the /_workitems/edit/<ID> link |
| The acceptance criteria come out empty | Your team writes them in the description and the Acceptance Criteria field is empty | Set acceptance_criteria_field: null in qa-stack.yaml |
| You added the server but it doesn't appear | The assistant wasn't restarted | VS Code: Developer: Reload Window · CLI: open a new session · Claude Desktop: quit the app completely |