Skip to content

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):

  1. lippia-neo-resolve-user-story-source recognizes that it's an Azure DevOps work item and checks that the link belongs to your configured organization.
  2. lippia-neo-fetch-user-story fetches the work item with all its fields through the azure-devops server.
  3. 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.
  4. It returns the story in memory, in the same format as a local story. It doesn't write any file.
  5. lippia-neo-read-user-story reads it and continues the normal QA flow.

NEO only 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.

  1. 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.
  2. Click New Token.
  3. 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
  1. Click Create and copy the token right away: you can't see it again later.
  2. 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-stack asks you all of this if you choose "stories in Azure DevOps", and it also builds .mcp.json for 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.json even if you use a different assistant. The NEO skills read AZURE_DEVOPS_ORG_URL from .mcp.json for 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.json with AZURE_DEVOPS_ORG_URL, lippia-neo-resolve-user-story-source considers 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 your az login session) and azure-identity (Azure credentials). NEO is documented and tested with pat.

What about Microsoft's official MCP? Microsoft publishes its own Azure DevOps MCP server. NEO uses @tiberriver256/mcp-server-azure-devops because it's the one in its template. Don't load both under the same name.


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 NEO the 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

  1. Restart the assistant (or reload the window). Servers are read at startup.
  2. Open the server list (/mcp in Claude Code or Codex, MCP: List Servers in VS Code…) and confirm that azure-devops shows as connected.
  3. 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