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/mcpthroughnpx, 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)
- Save
mcp.jsonfrom this page as.vscode/mcp.jsonin your repository (or merge theadoentry into an existing file). - Replace
{organization}with your Azure DevOps organization name — the part afterdev.azure.com/. - Open Copilot Chat in Agent mode and sign in with your work account when prompted.
- 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)
- Save the Claude Code config from this page as
.mcp.jsonin the repository root (or merge theadoentry). - Replace
{organization}. - Start
claudeand approve the project MCP server. The server's--authenticationoption acceptsinteractive,azcli,env,envvarandpat; with no option it signs you in interactively with your Microsoft Entra account.azclireuses an existingaz 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.comthrough 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-dlist (local) and reconnect the server. The Story Writer reports "read-only" when the write tools are absent; that is by design. get_changesunknown 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.