Azure DevOps MCP Setup: Choose Remote Entra or Local Interactive Login
If your client supports Microsoft’s Entra-backed remote flow, use the hosted Azure DevOps MCP server; otherwise run @azure-devops/mcp locally. Claude Desktop, Claude Code, Cursor, and Codex currently use the local path. Set the organization, authentication, and toolsets first, then verify read access before changing work items, repositories, builds, or tests.
If your client supports Microsoft’s Entra-backed remote flow, use the hosted Azure DevOps MCP server; otherwise run @azure-devops/mcp locally. Claude Desktop, Claude Code, Cursor, and Codex currently use the local path. Set the organization, authentication, and toolsets first, then verify read access before changing work items, repositories, builds, or tests.
Table of contents
- Should you use remote or local Azure DevOps MCP?
- How do you connect the right organization?
- Which authentication method should you choose?
- How do you verify projects, work items, and builds read-first?
- How do you limit toolsets and write access?
- How do you fix Entra, organization, Node, sign-in, and PAT failures?
- FAQ
Should you use remote or local Azure DevOps MCP?
Use Microsoft’s hosted remote server for supported Entra-backed clients, and use the local @azure-devops/mcp package for Claude, Cursor, Codex, or organizations that cannot complete the remote flow. Scope the organization and toolsets before touching work items, repositories, builds, or tests.
Microsoft recommends the remote server when the client supports its Entra registration flow. Claude Desktop, Claude Code, Cursor, and Codex currently use the local server because that required flow is not supported in those clients. The choice is therefore mainly determined by client compatibility, not by the Azure DevOps area you want to access. See the Azure DevOps MCP directory page for a practical starting point. (Azure DevOps MCP overview)
The local server runs through Node.js and connects to one named Azure DevOps organization. It can expose tools for work items, repositories, pull requests, builds, test plans, and documentation, so the initial configuration defines a meaningful permission boundary. MCP clients generally discover tools through a server connection; keeping that connection limited makes the resulting tool list easier to understand and control. (MCP architecture)
How do you connect the right organization?
Connect the local server by passing the Azure DevOps organization to npx; confirm that the organization name is correct before authenticating. The required command is:
npx -y @azure-devops/mcp <organization>
The local setup requires Node.js 20 or later. Replace <organization> with the organization identifier you intend to use, then make that same organization the one you verify in the client session. Do not begin by selecting a project from memory or assuming that a familiar project name identifies the correct organization.
A useful setup sequence is:
- Identify the exact Azure DevOps organization.
- Configure the remote or local server for that organization.
- Sign in with an identity that should have access there.
- Confirm the visible projects and a small set of read-only resources.
- Only then enable broader toolsets or write operations.
The Microsoft getting-started documentation covers the local installation flow and client configuration details. (Azure DevOps MCP getting started)
Which authentication method should you choose?
Choose interactive Microsoft login first when using the local server; it is the default and usually the clearest path for a human-operated client. Use Azure CLI, the Azure credential chain, a bearer-token environment variable, or a PAT only when that method matches your operating environment and credential policy.
Local authentication supports these methods:
- Interactive Microsoft login.
- Azure CLI credentials.
- The Azure credential chain.
- A bearer token supplied through an environment variable.
- A personal access token, or PAT.
Interactive login keeps the sign-in step visible and avoids placing a reusable secret directly in the client configuration. Azure CLI or the credential chain may fit an already managed developer environment. A bearer token can suit controlled automation, while a PAT should be treated as a sensitive credential with only the permissions and lifetime required by the organization.
Authentication proves who the server may act as; it does not replace Azure DevOps permissions. The selected identity still determines which projects, repositories, work items, builds, and tests are available. (Azure DevOps permissions)
How do you verify projects, work items, and builds read-first?
Verify the organization, project visibility, work items, repositories, and builds with read-only requests before enabling changes. Start with one known project and confirm that the returned resources match the intended organization and identity.
Use a narrow verification pass:
- Confirm the organization name in the client connection.
- List or inspect the expected project.
- Read a known work item without editing it.
- Inspect a repository or pull request without creating changes.
- Read a build or test-plan record without queuing or modifying anything.
- Check documentation access only if that toolset is needed.
This sequence separates connection problems from permission problems. If the project is missing, first check the organization and identity. If the project appears but a resource does not, check Azure DevOps permissions and the selected toolset. If a read succeeds but an attempted change is rejected, that is an expected permission boundary rather than proof that the server is misconfigured.
The server’s coverage includes work items, repositories, pull requests, builds, test plans, and documentation, so verification should follow the smallest useful slice of that surface. (Azure DevOps MCP overview)
How do you limit toolsets and write access?
Limit the enabled toolsets to the Azure DevOps areas required for the task, and keep the first session read-only wherever your client or workflow allows it. Configure work-item, repository, build, test-plan, pull-request, or documentation capabilities only when they are needed.
A practical boundary is:
| Need | Start with | Add later only if required |
|---|---|---|
| Issue triage | Work items, read access | Work-item changes |
| Code context | Repositories, pull requests, read access | Branch or pull-request actions |
| Pipeline diagnosis | Builds, read access | Build actions |
| Quality investigation | Test plans, read access | Test-plan changes |
| Project guidance | Documentation, read access | Any write-capable area |
Toolset names and configuration behavior should follow Microsoft’s current toolset documentation rather than guessed flags or client-specific assumptions. (Azure DevOps MCP toolsets)
Also review the client’s configuration before connecting it to a shared workspace. The Codex client guide can help with the client-side path, while the config validator is a useful practical next step for checking configuration structure before sign-in.
How do you fix Entra, organization, Node, sign-in, and PAT failures?
Fix failures in order: client compatibility, Node.js version, organization value, authentication method, then Azure DevOps permissions. This order prevents a permission investigation from masking a missing local runtime or an unsupported remote Entra flow.
| Symptom | Likely boundary | Next check |
|---|---|---|
| Remote setup cannot finish | Client does not support the Entra registration flow | Use the local server for Claude Desktop, Claude Code, Cursor, or Codex |
npx setup fails immediately | Node.js is below version 20 or unavailable | Install or select Node.js 20+ |
| The wrong projects appear | Organization or identity is incorrect | Recheck <organization> and sign-in account |
| Interactive login does not complete | Browser or account authentication issue | Retry interactive Microsoft login, then consider an approved alternate method |
| PAT authentication fails | Token, scope, expiry, or permission issue | Recheck the PAT and the Azure DevOps permissions for its identity |
For the local path, confirm the package command and organization value exactly:
npx -y @azure-devops/mcp <organization>
If the client is supported for Microsoft’s hosted server, revisit the Entra setup instead of forcing local credentials into that flow. If the client is one of the currently local-only cases, use interactive login or another supported local method.
Finally, separate authentication from authorization. A successful sign-in does not grant access to every project or operation; Azure DevOps permissions remain the main boundary. Keep tokens private, avoid placing credentials in shared prompts or logs, and follow the MCP security guidance. (MCP security best practices)