Azure DevOps MCP Server

When developing tools for the Azure DevOps MCP server, you must adhere to strict naming constraints required by the Claude API. Failure to comply will result in 400 errors during API requests.

Naming Constraints

• Pattern: ^[a-zA-Z0-9_.-]{1,64}$
• Allowed Characters: Alphanumeric (a-z, A-Z, 0-9), underscores (_), dots (.), and hyphens (-).
• Forbidden: Spaces, forward slashes (/), and other special characters (e.g., @, #, $, %).
• Length Limits:
  • Tool Names: 1 to 64 characters.
  • Parameter Names: 1 to 64 characters (though keeping them $\le$ 32 characters is recommended for readability).

You can perform complex workflows involving retrieving work item details, summarizing comments, updating fields, and assigning ownership.

Retrieve and Summarize:

Get work item 12345 and show me fields ID, Type, State, Repro Steps, Story Points, and Priority. Get all comments for the work item and summarize them for me.

Update Fields:

Polish the Repro Steps with more information and details. Then take that value and update the work item. Also update StoryPoints = 5 and State = Active.

Assign and Comment:

Assign this work item to myemail@outlook.com and add a comment "I will own this Bug and get it fixed"

To access the latest features before they are released in the stable version, update your mcp.json configuration to use the @next tag for the @azure-devops/mcp package.

{
  "inputs": [
    {
      "id": "ado_org",
      "type": "promptString",
      "description": "Azure DevOps organization name  (e.g. 'contoso')"
    }
  ],
  "servers": {
    "ado": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp@next", "${input:ado_org}"]
    }
  }
}

If strict tenant admin policies prevent the OAuth flow from working (resulting in an error message in the browser after login), fall back to the Azure CLI authentication method.

1. Install Azure CLI and run az login.
2. Update your .vscode/mcp.json to use the azcli authentication option.

{
  "inputs": [
    {
      "id": "ado_org",
      "type": "promptString",
      "description": "Azure DevOps organization name (e.g. 'contoso')"
    }
  ],
  "servers": {
    "ado": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "${input:ado_org}", "--authentication", "azcli"]
    }
  }
}

Codex uses ~/.codex/config.toml for configuration. You can add the server via the CLI or by editing the config file directly.

Interactive (Default):

codex mcp add azure-devops -- npx -y @azure-devops/mcp Contoso

Azure CLI Authentication: If you are already signed in via Azure CLI:

az login
codex mcp add azure-devops -- npx -y @azure-devops/mcp Contoso --authentication azcli

Manual Configuration: Edit ~/.codex/config.toml:

[mcp_servers.azure-devops]
command = "npx"
args = ["-y", "@azure-devops/mcp", "Contoso"]

For automated scenarios or when you want to use a token stored in an environment variable, use the envvar authentication type. This is the recommended method for headless environments (WSL2, SSH, Docker, CI runners).

1. Set the ADO_MCP_AUTH_TOKEN environment variable with your PAT:

   export ADO_MCP_AUTH_TOKEN="your-azure-devops-token"

2. Use the --authentication envvar flag when running the server via npx or update your .vscode/mcp.json as shown below.

{
  "inputs": [
    {
      "id": "ado_org",
      "type": "promptString",
      "description": "Azure DevOps organization name (e.g. 'contoso')"
    }
  ],
  "servers": {
    "ado": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "${input:ado_org}", "--authentication", "envvar"]
    }
  }
}

To triage work effectively, first retrieve the team's iterations and backlog levels to provide context to the LLM.

1. List context:

list iterations for Contoso team
list backlog levels for Contoso team

2. Execute triage: Instruct the model to identify specific types of work (e.g., security bugs) and assign them to iterations:

List of work items for Stories backlog. But then go thru and find all the security related bugs. Assign the first 4 to the current iteration. If there are more than four, assign the rest to the next iteration. Then find 2-3 high priority user stories and assign them to the current iteration. Do it!