Azure DevOps MCP Server: Connect Claude, Copilot or Cursor

Microsoft publishes one official Azure DevOps MCP server in two forms. The remote server is hosted by Azure DevOps at https://mcp.dev.azure.com/{organization}, speaks streamable HTTP and signs you in with Microsoft Entra ID. The local server is the npm package @azure-devops/mcp, started with npx and connected over stdio. Microsoft recommends the remote one and says it will eventually replace the local one, but not every assistant can sign in to it yet: VS Code with GitHub Copilot works out of the box, Claude Code and Cursor need a custom Entra app registration, and Claude Desktop and Codex have to use the local server. This guide covers both routes, the toolsets, the work item tools and read-only mode.

It is a setup guide for one vendor’s server. If MCP itself is new to you, start with what MCP is.

Before you start

• Azure DevOps Services, the cloud version. The project’s FAQ↗ (opens in a new tab) says the server supports only Azure DevOps Services, because several API endpoints it needs are not available on premises, and there are no plans to support Azure DevOps Server.
• An organisation backed by a Microsoft Entra tenant. Standalone Microsoft account organisations are not supported for the remote server, and the local server’s FAQ says personal accounts are refused too.
• Membership of the projects you want to query. The server sees what your account can see.
• For the local server only: Node.js 20 or later.
• An assistant in agent mode. Microsoft’s overview says the server needs the assistant to operate in agent mode to reach Azure DevOps data.

Remote or local: which one your assistant can use

The deciding factor is sign-in. Microsoft’s remote server guide↗ (opens in a new tab) explains that Entra ID does not support the dynamic client registration flow that some MCP clients rely on, so a client either ships with its own registration or you make one for it.

• Works with the remote server directly: VS Code with GitHub Copilot, Visual Studio, GitHub Copilot CLI, the GitHub Copilot app, Microsoft Foundry and Microsoft Copilot Studio.
• Remote with a custom Entra app registration: Claude Code, Cursor desktop and Cursor Cloud Agents.
• Local server only, for now: Claude Desktop and Codex.

VS Code with GitHub Copilot (remote)

Add a .vscode/mcp.json to the repository, replacing contoso with your organisation name. Open the Chat view in a Local session with Agent selected, sign in with your Entra account when prompted, and the tool list appears. It has to be Local: the Copilot harness↗ (opens in a new tab) can currently reach only local MCP servers that don’t need authentication. Before committing an MCP file for a team, it is worth reading how VS Code decides which servers to trust.

{
  "servers": {
    "ado-remote-mcp": {
      "url": "https://mcp.dev.azure.com/contoso",
      "type": "http",
      "headers": {
        "X-MCP-Toolsets": "wit,work",
        "X-MCP-Readonly": "true"
      }
    }
  },
  "inputs": []
}

You can leave the organisation off the URL, but then every tool call has to name it. The two headers are optional and explained below; leaving both out gives you every tool, read and write.

Claude Code (remote, with an Entra app)

Someone with rights in your tenant registers an application in the Microsoft Entra admin center: a Mobile and desktop redirect URI of http://localhost:3118/callback, public client flows allowed, and delegated API permissions on the Azure DevOps MCP enterprise application, followed by admin consent. Microsoft’s advice is to grant only the scopes the client needs, and read scopes alone if you only use read tools. Then add the server with the new application’s client ID:

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

Start claude, run /mcp, choose ado and complete the browser sign-in. The --client-id and --callback-port flags are how Claude Code handles servers without dynamic client registration↗ (opens in a new tab); the port must match the redirect URI you registered. The same settings can go in a project .mcp.json as an oauth object with clientId and callbackPort.

Cursor (remote, with an Entra app)

Cursor needs its own registration with a redirect URI of http://localhost:8787/callback. In Settings > Tools & MCP, add a new MCP server with the URL https://mcp.dev.azure.com, type http, and an auth object holding your CLIENT_ID, then select Authenticate. Cursor Cloud Agents need a web redirect URI and a client secret as well; Microsoft’s guide lists the exact values. More on Cursor and MCP generally is on the Cursor integration page.

The local server (Claude Desktop, Codex, or no app registration)

If you cannot get an Entra app registered, the local server works in every client above. The getting started guide↗ (opens in a new tab) gives each client’s form. For Claude Code:

claude mcp add --transport stdio azure-devops -- \
  npx -y @azure-devops/mcp contoso -d core work work-items

On first use a browser window opens for Microsoft sign-in; that interactive login is the default. The --authentication argument (or -a) switches to azcli for an existing az login session, env for the Azure credential chain, envvar for a bearer token in ADO_MCP_AUTH_TOKEN, or pat for a personal access token supplied base64-encoded in PERSONAL_ACCESS_TOKEN. Keep tokens out of committed configuration files. Claude Desktop and Codex take the same npx command in their own configuration format.

Narrowing the tools

Both servers expose a lot of tools, and a shorter list helps the model choose. On the remote server, the X-MCP-Toolsets header takes a comma-separated list: repos, advsec, wit (work items and work item search), pipelines, wiki, work (iterations and capacity), testplan and elm, with all as the default. Core tools such as core_list_projects stay available. X-MCP-Tools names individual tools instead, and Microsoft says not to combine the two headers.

The local server uses domains instead, passed after -d: core, work, work-items, search, test-plans, repositories, wiki, pipelines and advanced-security. Always include core, which the agent needs to look up projects. Leaving -d out loads everything.

Work item tools

The work item tools are grouped dispatchers: one tool with an action parameter. On the remote server, wit_work_item reads (get, get_batch, my, list_comments, list_revisions, list_for_iteration), wit_query runs saved queries, wit_backlog lists backlogs and search_workitem does full-text search. Writes sit in separate tools: wit_work_item_write (create, update, update in batch, add a child), wit_work_item_comment_write and wit_work_item_link_write, which can link a work item to a pull request. Ad hoc WIQL through wit_query_by_wiql is currently limited to Insiders on the remote server. Prompts that work well as a first session:

• “List the projects in my Azure DevOps organisation.”
• “Show my assigned work items in Payments, newest changes first.”
• “List the work items in the current iteration for the Payments team and flag anything still New.”
• “Summarise work item 4521 with its comments and revision history.”

Tool names have changed before. The repository README warns that a recent consolidation renamed tools, and suggests pinning @azure-devops/mcp@2.8.1 temporarily if that breaks your prompts or skills. If an instruction file names a tool, check it against the current list.

Read-only use and whose rights it uses

Send X-MCP-Readonly: true and the remote server offers only read tools; it combines with a toolset header, as in the example above. It is the sensible way to start. The assistant always works as you: Microsoft states that OAuth scopes never override the signed-in user’s permissions, and an operation succeeds only when both the app’s scopes and your Azure DevOps permissions allow it. Enabling a toolset grants nothing extra.

Your client adds its own layer. Claude Code asks before an MCP tool call unless you pre-approve it; allow reads such as mcp__ado__wit_work_item and keep the _write tools on ask. How approval rules work is covered in auto-approve in Claude Code.

Limits to know

• One organisation at a time. The FAQ says you can switch, but not connect to two at once.
• No Azure DevOps Server. Cloud organisations only, with no on-premises plan.
• Stale answers. Microsoft suggests adding “Do not use previously fetched data” to a prompt when you need fresh results.
• Rights are yours, not the assistant’s. There is no separate identity with narrower permissions; changes appear under your name.

Removing it

claude mcp remove ado

In VS Code, delete the entry from .vscode/mcp.json. If you issued a personal access token for the local server, revoke it in Azure DevOps; if an Entra app was registered only for this, ask your admin to remove it or its consent.

If the work is a task list

Azure DevOps suits teams already running Boards, Repos and Pipelines together. If what you need is a plain list of features, enhancements and bugs that people outside the engineering team can work on too, fenbs is a board with four lanes where an AI assistant is a member with its own role, connected over OAuth to https://fenbs.ai/api/mcp with scopes you choose, and every change is recorded under the name of whoever made it. The setup is on the MCP docs page.