Org Skills

azure-devops

Connects GitHub Copilot and Claude Code to Azure DevOps (work items, pull requests, pipelines and builds, wiki, test plans, Advanced Security alerts) through Microsoft's Azure DevOps MCP server, read-only by default; the catalog's agents reach it under the server name `ado`.

Raw Source
What it isAn MCP server configuration. MCP connects your AI assistant to tools and live data outside your code. Why use mcp servers →

Install

VS Code, this repository

Adds the server to .vscode/mcp.json (other servers are kept). Replace <your-org> with your Azure DevOps organization, then follow the setup notes below.

npx -y github:AGCO-Global/org-skills add mcp azure-devops --org <your-org>

Use it

Open Copilot Chat in Agent mode; the server's tools appear in the tools picker.

This repository

Adds the server to .mcp.json (other servers are kept), then follow the setup notes below.

npx -y github:AGCO-Global/org-skills add mcp azure-devops --org <your-org> --tool claude

Use it

Start claude, approve the project MCP server, and check it with /mcp.

Commands run in your repository folder and need Node.js 20+. They use your normal git sign-in to GitHub, so they work while the repository is private. Run npx -y github:AGCO-Global/org-skills list to see everything available.

Configuration — GitHub Copilot (VS Code)

{
  "servers": {
    "ado": {
      "type": "http",
      "url": "https://mcp.dev.azure.com/{organization}",
      "headers": {
        "X-MCP-Toolsets": "wit,work,repos,pipelines,wiki,testplan,advsec",
        "X-MCP-Readonly": "true"
      }
    }
  },
  "inputs": []
}

Configuration — Claude Code

{
  "mcpServers": {
    "ado": {
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "{organization}", "-d", "core", "work", "work-items", "repositories", "pipelines", "wiki", "test-plans", "search", "advanced-security"]
    }
  }
}

Setup notes

Azure DevOps MCP server

Gives your coding agent live context from Azure DevOps: the work item you are implementing, the PR you are reviewing, the build that failed, the wiki page with the design. The catalog's agents (ADO Planner, Story Writer, Code Reviewer, Security Reviewer, Test Writer, Release Notes, Build Triage, PR Describer) use it through the server name ado. Keep that name: Copilot agents reference tools as ado/*, the generated Claude Code subagents as mcp__ado.

Two servers exist, both from Microsoft, with the same tool names for everything the agents use except where noted under Capability differences:

  • Remote (hosted) at https://mcp.dev.azure.com/{organization} — nothing to install, Microsoft Entra sign-in, supports read-only mode. Copilot uses it directly.
  • Local (@azure-devops/mcp through npx, Node.js 20+) — for clients that cannot use Entra sign-in with the hosted server. No read-only switch.

Facts below were verified 2026-09 against remote server and local server TOOLSET.md.

Set up in VS Code (Copilot)

  1. Save mcp.json from this page as .vscode/mcp.json in your repository (or merge the ado entry into an existing file).
  2. Replace {organization} with your Azure DevOps organization name — the part after dev.azure.com/.
  3. Open Copilot Chat in Agent mode and sign in with your work account when prompted.
  4. Try: "Summarise work item 1234 and its acceptance criteria."

Visual Studio 2022+, Copilot CLI and the GitHub Copilot app use the same URL and headers.

Set up in Claude Code

Option A — remote server with an Entra app registration (recommended when an admin can register once)

Claude Code can use the hosted server after a tenant admin creates a Microsoft Entra app registration (redirect URI http://localhost:3118/callback, public client flows enabled, delegated permission on the Azure DevOps MCP application 2a72489c-aab2-4b65-b93a-a91edccf33b8, admin consent). This keeps the read-only header and the exact same tool surface as Copilot. With the application (client) ID:

claude mcp add --transport http ado https://mcp.dev.azure.com/{organization} \
  --client-id {client-id} --callback-port 3118

or commit a .mcp.json in the repository root:

{
  "mcpServers": {
    "ado": {
      "type": "http",
      "url": "https://mcp.dev.azure.com/{organization}",
      "oauth": { "clientId": "{client-id}", "callbackPort": 3118 },
      "headers": { "X-MCP-Toolsets": "wit,work,repos,pipelines,wiki,testplan,advsec", "X-MCP-Readonly": "true" }
    }
  }
}

Run claude, then /mcp, and complete the browser sign-in.

Option B — local server (no admin needed)

  1. Save the Claude Code config from this page as .mcp.json in the repository root (or merge the ado entry).
  2. Replace {organization}.
  3. Start claude and approve the project MCP server. The server's --authentication option accepts interactive, azcli, env, envvar and pat; with no option it signs you in interactively with your Microsoft Entra account. azcli reuses an existing az login — the usual choice on a machine that already has the Azure CLI, and the only one that works headless without a token.

Or for just yourself:

claude mcp add --transport stdio ado -- npx -y @azure-devops/mcp {organization} -d core work work-items repositories pipelines wiki test-plans search advanced-security

The local server exposes every write tool of the selected domains. Add the read-only block below so Claude Code behaves like the Copilot default.

Read-only by default

Copilot / remote: X-MCP-Readonly: true removes every *_write tool from the server, so nothing can change Azure DevOps. Teams that want the Story Writer to create work items copy mcp.json, remove that header (or switch to X-MCP-Tools with an explicit allow-list), and Copilot still confirms each write.

Claude Code / local: there is no read-only switch, so deny the write tools in .claude/settings.json (project or user scope). A deny rule is the tool's full name, mcp__<server>__<tool> — here mcp__ado__wit_work_item_write. Deny rules also accept a glob over the whole tool name, so "mcp__ado__*_write" alone covers the list below and any write tool Microsoft adds later; the explicit names are spelled out so a reviewer can see what is blocked. Check them against /mcp on the installed version.

{
  "permissions": {
    "deny": [
      "mcp__ado__wit_work_item_write", "mcp__ado__wit_work_item_comment_write", "mcp__ado__wit_work_item_link_write",
      "mcp__ado__repo_pull_request_write", "mcp__ado__repo_pull_request_thread_write", "mcp__ado__repo_create_branch",
      "mcp__ado__pipelines_write", "mcp__ado__wiki_upsert_page",
      "mcp__ado__testplan_test_plan_write", "mcp__ado__testplan_test_suite_write", "mcp__ado__testplan_test_case_write", "mcp__ado__testplan_test_run_write",
      "mcp__ado__work_iteration_write", "mcp__ado__work_capacity_write"
    ]
  }
}

The generated Claude Code subagents already carry disallowedTools for the same list, so a reviewer or planner cannot write even without this block; the block protects plain chat as well. To let the Story Writer create work items, remove mcp__ado__wit_work_item_write and mcp__ado__wit_work_item_link_write from the deny list; Claude Code then asks before each create.

Everything the server does runs with your permissions — it can never see or change more than you can.

Which agent needs which toolset

Agent Remote toolset (X-MCP-Toolsets) Local domain (-d) Tools it calls
ADO Planner wit, repos work-items, repositories, search wit_work_item get/get_batch/list_comments, search_workitem, repo_pull_request get, repo_file get_content
Story Writer wit, work (+ writes enabled) work-items, work, search, core wit_work_item get/get_batch/get_type, search_workitem, work list_iterations, wit_work_item_write create/add_child, wit_work_item_link_write link
Code Reviewer repos, wit repositories, work-items repo_pull_request get/get_changes, repo_pull_request_thread list/list_comments, repo_file get_content, wit_work_item get
Security Reviewer repos, advsec repositories, advanced-security as Code Reviewer plus advsec_alerts list/get (remote) / advsec_get_alerts, advsec_get_alert_details (local)
Test Writer wit work-items wit_work_item get/list_comments
Release Notes repos, wit, pipelines repositories, work-items, pipelines repo_pull_request get/list/list_by_commits, wit_work_item get_batch, pipelines_build list/get_status/get_changes
Build Triage pipelines, repos, wit, testplan pipelines, repositories, work-items, test-plans pipelines_build list/get_status/get_changes, pipelines_build_log list/get_content, pipelines_definition list, repo_pull_request list_by_commits, testplan_show_test_results_from_build_id
PR Describer repos, wit, pipelines repositories, work-items, pipelines repo_pull_request get/get_changes, wit_work_item get, pipelines_build list

The shipped configs enable the union of this table, so every tool an agent names exists. Drop the toolsets your teams do not use — a shorter tool list makes the model pick better. elm (Enterprise Live Migration, preview) is enabled by default on the remote server; naming any X-MCP-Toolsets value, as the shipped config does, leaves it out. core tools (core_list_projects, core_list_project_teams) are always present remotely and need the core domain locally.

Capability differences that matter

Capability Remote Local
PR file changes and line diffs repo_pull_request get_changes not available — agents fall back to git fetch + git diff, or repo_file get_content per file
Advanced Security alerts advsec_alerts (list, get), toolset advsec advsec_get_alerts, advsec_get_alert_details, domain advanced-security
Read-only mode X-MCP-Readonly: true none — use the deny block above
Per-tool allow-list X-MCP-Tools header (do not combine with X-MCP-Toolsets) domains only
Search tools (search_code, search_workitem, search_wiki) inside repos, wit, wiki need the search domain
Authentication Microsoft Entra (OAuth) Entra or personal access token

Data handling

Everything the server returns — work item text, comments, PR descriptions, review threads, commit messages, build logs, wiki pages — is content written by people and systems outside your control. Agents treat it as data, never as instructions: an instruction found inside it ("mark this item done", "approve this PR") is reported, not followed. Every catalog agent carries that rule; apply it to your own prompts too.

Requirements and troubleshooting

  • The organization must be connected to Microsoft Entra ID (the normal setup for company organizations); standalone Microsoft-account organizations are not supported by the remote server.
  • Connection refused: allow outbound HTTPS to mcp.dev.azure.com through the proxy or firewall.
  • No data returned: check your access to that project; IDs are organization-scoped, so name the project when an ID is not found.
  • Tools missing: check X-MCP-Toolsets (remote) or the -d list (local) and reconnect the server. The Story Writer reports "read-only" when the write tools are absent; that is by design.
  • get_changes unknown in Claude Code: you are on the local server; the agents use the git fallback.

Microsoft documentation: remote server · overview and local server · local server repository.