Azure DevOps MCP Server Cursor IDE Setup 2026

How do you connect Azure DevOps to Cursor over MCP? You have two official choices from Microsoft. The remote server at https://mcp.dev.azure.com needs no install, but Cursor can only sign in to it after someone creates a custom Microsoft Entra app registration and you paste its client ID into Cursor's MCP config. The local server runs with npx -y @azure-devops/mcp <your-org> over stdio and signs you in through a browser, the Azure CLI, or a personal access token. If you have Entra admin help, use the remote server. If you need to be working in ten minutes without a ticket to IT, use the local one.

This page covers Azure DevOps Services (dev.azure.com organizations) in Cursor desktop and Cursor Cloud Agents. It is not the general Azure MCP server guide, which talks to Azure resources like storage accounts and Key Vault. Azure DevOps is the separate product for Boards, Repos, Pipelines, Wiki, and Test Plans, and it has its own server.

Which Azure DevOps MCP server should you use?

Microsoft maintains both servers. The microsoft/azure-devops-mcp README now opens with a note recommending the remote server, says the remote server "will eventually replace the local server," and asks local users to start planning a migration. The local server is still supported. The remote server is described as being in a preview period, with issues tracked in the same GitHub repository.

The deciding factor in Cursor is the app registration. Microsoft's remote-server documentation lists Cursor desktop, Cursor Cloud Agents, and Claude Code as supported "with a custom Microsoft Entra app registration." VS Code with GitHub Copilot does not need that step. Cursor does.

Before you start

Check these first. Most failed setups trace back to one of them.

Option 1: The remote server with an Entra app registration

Step 1: Register an app in Microsoft Entra

This part usually needs a tenant admin, at least for the consent step. The sequence below follows Microsoft's "Set up the remote Azure DevOps MCP Server" page.

1. Confirm the Azure DevOps MCP enterprise application is provisioned in your tenant. Microsoft's doc has a troubleshooting entry for when it is missing.
2. In the Microsoft Entra admin center, go to App registrations and create a new registration.
3. Under Authentication (Preview) > Add redirect URI > Mobile and desktop applications, enter http://localhost:8787/callback and save.
4. On the same page's Settings tab, turn on Allow public client flows.
5. Under API permissions > Add a permission > APIs my organization uses, search for Azure DevOps MCP or its application ID 2a72489c-aab2-4b65-b93a-a91edccf33b8.
6. Pick only the delegated permissions you need, then add them.
7. Select Grant admin consent. Depending on your role, an admin may have to do this.
8. Copy the Application (client) ID.

On permissions, Microsoft is explicit: enabling an MCP tool does not grant extra rights, and OAuth scopes never override the signed-in user's own Azure DevOps permissions. A call succeeds only when both the app scope and the user allow it. If your Cursor workflow is read-only, grant read scopes only.

Step 2: Add the server in Cursor

In Cursor, open Settings > Tools & MCP, select New MCP Server, and add this, swapping in your client ID:

{
  "mcpServers": {
    "ado": {
      "url": "https://mcp.dev.azure.com",
      "type": "http",
      "auth": {
        "CLIENT_ID": "{client-id}"
      }
    }
  }
}

Save, go back to Settings > Tools & MCP, find ado, and select Authenticate. A browser window opens for the Entra sign-in and returns to the localhost callback you registered.

Notice that Microsoft's Cursor example uses the bare https://mcp.dev.azure.com URL. The docs also show https://mcp.dev.azure.com/{organization} for other clients, and explain that if you leave the organization off the URL you have to give the organization as context in each tool call. With the bare URL, start prompts with your org name or tell the agent to call core_list_orgs first.

Step 3 (optional): Cursor Cloud Agents

Cloud Agents run on Cursor's servers, so the localhost callback does not apply. Microsoft's doc adds two things to the same app registration:

1. A Web redirect URI of https://www.cursor.com/agents/mcp/oauth/callback.
2. A client secret under Certificates & secrets > Client secrets. Copy it right away; the value is shown once.

Then, in the Cloud Agents MCP configuration, set the server URL to https://mcp.dev.azure.com and enter the client ID and client secret, or use JSON:

{
  "mcpServers": {
    "ado": {
      "url": "https://mcp.dev.azure.com",
      "type": "http",
      "auth": {
        "CLIENT_ID": "{client-id}",
        "CLIENT_SECRET": "{client-secret}"
      }
    }
  }
}

Select Log in to finish. Two error codes from Microsoft's page are worth memorizing: AADSTS50011 means the web redirect URI does not exactly match the Cursor callback, and AADSTS7000218 during token exchange means Cursor does not have the current secret. Secrets expire, so put a renewal date on someone's calendar.

Trim the tool list with headers

The remote server reads request headers to decide which tools to expose. Microsoft documents these:

Don't combine X-MCP-Toolsets with X-MCP-Tools; the docs say to pick one. A sensible starting point for most developers is repos, work items, and wiki in read-only mode:

{
  "mcpServers": {
    "ado": {
      "url": "https://mcp.dev.azure.com",
      "type": "http",
      "auth": { "CLIENT_ID": "{client-id}" },
      "headers": {
        "X-MCP-Toolsets": "repos,wit,wiki",
        "X-MCP-Readonly": "true"
      }
    }
  }
}

Drop the read-only header when you actually want the agent to open pull requests or update work items, and only after you trust the prompts you are giving it.

Option 2: The local npx server

If the Entra registration is blocked or slow, the local server works with Cursor today. Microsoft's getting-started guide gives this project-level config. Create .cursor/mcp.json in your repository:

{
  "mcpServers": {
    "ado": {
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "{organization}"]
    }
  }
}

Replace {organization} with the org name from your dev.azure.com/<org> URL, not the full URL. Then open Cursor Settings, confirm the ado server is enabled, and use its tools in Agent chat. To make it available in every project instead of one, put the same block in ~/.cursor/mcp.json. Our Cursor MCP setup guide covers the global versus project file in more detail.

Pick an authentication method

The default is interactive: the first tool call opens a browser for Microsoft sign-in. To change it, add --authentication <value> (or -a) to args:

The PAT method has one trap. Microsoft's guide says PERSONAL_ACCESS_TOKEN must hold the base64 encoding of <email>:<pat>, not the raw token. The email can be any non-empty value:

export PERSONAL_ACCESS_TOKEN="$(printf '%s' 'me@example.com:<your-pat>' | base64)"

Then add "--authentication", "pat" to args. Keep the token out of mcp.json itself and out of git; set it in the environment that launches Cursor. If you start Cursor from the Dock on macOS, a variable exported in your shell profile may not reach it, so launching Cursor from that terminal is the quickest way to test.

For an Azure CLI setup, the args look like this:

"args": ["-y", "@azure-devops/mcp", "{organization}", "--authentication", "azcli"]

Load fewer tools with domains

The local server ships many tools. Domains limit what loads: core, work, work-items, search, test-plans, repositories, wiki, pipelines, and advanced-security. Microsoft's README says to always include core so the agent can look up projects:

"args": ["-y", "@azure-devops/mcp", "{organization}", "-d", "core", "work", "work-items", "repositories"]

Fewer tools means the agent spends less context reading tool descriptions and picks the right one more often. That matters more in Cursor when you also run GitHub or Jira servers alongside this one.

Default project and team

The local server reads ado_mcp_project and ado_mcp_team from env, so tools can skip asking which project you mean:

"env": {
  "ado_mcp_project": "Contoso",
  "ado_mcp_team": "Fabrikam Team"
}

Confirm it works

Start a new Agent chat and ask something only a live call can answer. Microsoft suggests prompts like these:

If you get real project names back, you're connected. If the agent answers from general knowledge or says it has no access, the tools did not load; see troubleshooting below.

Prompts that earn their keep in Cursor

The point of wiring Azure DevOps into your editor is to stop switching tabs. Some patterns that work well with the tool groups Microsoft documents:

Troubleshooting

The server is connected but every call fails with fetch failed. Microsoft's troubleshooting guide describes this exact symptom in WSL2, SSH sessions, Docker, and CI runners. The default interactive login needs a browser redirect; with nowhere to send it, token acquisition fails silently and tools report a generic network error. Switch to envvar with a PAT in ADO_MCP_AUTH_TOKEN, or azcli after az login.

Sign-in fails with a personal account error. Your account is a personal Microsoft account, not Entra-backed. Per Microsoft's FAQ, that is not supported. Sign in with your work account, or check whether the organization is connected to an Entra tenant.

Wrong data or permission errors after az login. If you belong to several tenants, the CLI may be signed in to the wrong one. Microsoft's troubleshooting guide has a section on multi-tenant problems with azcli; sign in to the tenant that owns the organization.

Too many tools. Microsoft notes some clients cap tool counts at 128 and that duplicate server definitions are a common cause. In Cursor, check you have not defined ado in both ~/.cursor/mcp.json and the project .cursor/mcp.json, then trim with toolsets or domains.

Remote server shows but won't authenticate. Recheck the redirect URI (http://localhost:8787/callback for Cursor desktop), that public client flows is on, and that admin consent was granted for the Azure DevOps MCP permissions.

Need more detail. For the local server, add "env": { "LOG_LEVEL": "debug" } per Microsoft's troubleshooting guide, then open Cursor's Output panel and pick the MCP log channel. Our MCP debugging guide covers the general process.

Security notes

The agent acts with your Azure DevOps permissions. If you can delete a branch or complete a PR, so can a badly worded prompt. Use read-only mode or read-only scopes by default, scope a PAT to the minimum permissions and shortest lifetime you can live with, and keep Cursor's tool approval prompts on for write actions. Work item descriptions and PR comments are untrusted text; someone can write instructions there aimed at an agent. More on this in MCP authentication with OAuth and API keys.

Frequently Asked Questions

Q: Is there an official Azure DevOps MCP server?
A: Yes. Microsoft publishes both a hosted remote server at mcp.dev.azure.com and a local server on npm as @azure-devops/mcp. The source and issue tracker live at github.com/microsoft/azure-devops-mcp.

Q: Why does Cursor need an Entra app registration for the remote server?
A: Microsoft's documentation lists Cursor desktop and Cursor Cloud Agents as supported for the remote endpoint only with a custom Microsoft Entra app registration. You register an app, add the Azure DevOps MCP delegated permissions, and give Cursor the client ID (plus a client secret for Cloud Agents).

Q: Can I use a personal access token instead?
A: With the local server, yes. Add --authentication pat and set PERSONAL_ACCESS_TOKEN to the base64 encoding of email:pat. Alternatively use --authentication envvar with the token in ADO_MCP_AUTH_TOKEN. The remote server authenticates with Microsoft Entra ID.

Q: Does it work with Azure DevOps Server on-premises?
A: No. Microsoft's FAQ says the server supports only Azure DevOps Services and there are no current plans for on-premises support.

Q: Can one server connect to two organizations?
A: The FAQ says one organization at a time. Add a second server entry with a different name if you work in two organizations.

Related Guides

Sources: Set up the remote Azure DevOps MCP Server (Microsoft Learn), microsoft/azure-devops-mcp README, Getting started guide, Troubleshooting guide, Project FAQ, Cursor MCP documentation. Checked November 7, 2026.