Set up the remote Azure DevOps MCP Server

Azure DevOps Services

The remote Azure DevOps MCP Server is a hosted version of the Azure DevOps MCP Server that doesn't require a local installation. Instead of running the server on your machine, you connect your AI assistant directly to the Azure DevOps–hosted endpoint by using streamable HTTP transport.

Choose remote first

Use the remote MCP Server when your environment supports it. The remote server is the recommended option because Azure DevOps hosts and updates it, and you don't need to install Node.js or manage a local server process.

Use the local MCP Server when your client can't authenticate to the remote server with Microsoft Entra ID. This limitation currently applies to clients such as Claude Desktop and Codex. Cursor and Claude Code require a custom Microsoft Entra app registration to authenticate. For local setup instructions, see Enable AI assistance with the Azure DevOps MCP Server.

Prerequisites

mcp.json configuration

{
  "servers": {
    "ado-remote-mcp": {
      "url": "https://mcp.dev.azure.com/{organization}",
      "type": "http"
    }
  },
  "inputs": []
}

You can also omit the organization name from the URL. However, if you omit the organization name, you must provide it as context in each tool call.

{
  "servers": {
    "ado-remote-mcp": {
      "url": "https://mcp.dev.azure.com/",
      "type": "http"
    }
  },
  "inputs": []
}

Toolsets

Specify toolsets to restrict the tools available to the MCP server. Shouldn't be combined with X-MCP-Tools.

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

Read-only tools

Use the X-MCP-Readonly header to restrict the server to read-only operations. This restriction is useful when you want to prevent modifications to Azure DevOps resources.

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

Combine toolsets and read-only filtering

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

Individual tools

Use the X-MCP-Tools header to enable only specific tools. Shouldn't be combined with X-MCP-Toolsets.

Specify tool names that appear in the available tools list. For consolidated tools such as wit_work_item, choose the operation by using the tool's action parameter when you call it.

{
  "servers": {
    "ado-remote-mcp": {
      "url": "https://mcp.dev.azure.com/{organization}",
      "type": "http",
      "headers": {
        "X-MCP-Tools": "core_list_projects, wit_work_item"
      }
    }
  },
  "inputs": []
}

Insiders

As we experiment and introduce new tools and updates to existing ones, you can get early access to these changes by using the X-MCP-Insiders header.

{
  "servers": {
    "ado-remote-mcp": {
      "url": "https://mcp.dev.azure.com/{organization}",
      "type": "http",
      "headers": {
        "X-MCP-Insiders": "true"
      }
    }
  },
  "inputs": []
}

Available tools

Core tools

Core tools are always available unless noted otherwise.

Work

The work tools are consolidated into grouped dispatchers using an action parameter.

Repos

The repository tools are consolidated into grouped dispatchers using an action parameter.

Wit

The work item tools are consolidated into grouped dispatchers using an action parameter.

Pipelines

The pipeline tools are consolidated into grouped dispatchers using an action parameter.

Wiki

The wiki read operations are consolidated into a single wiki tool. Use the action parameter to select the operation.

Test plans

The test plan tools are consolidated into grouped dispatchers using an action parameter.

Advanced Security

The Advanced Security tools are consolidated into a grouped dispatcher that uses an action parameter.

Enterprise Live Migration (preview)

The Enterprise Live Migration tools use an action parameter to group and dispatch tasks. Learn more about the Enterprise Live Migration preview.

To make only the Enterprise Live Migration tools available, use the X-MCP-Toolsets header with the elm value:

{
  "servers": {
    "ado-remote-mcp": {
      "url": "https://mcp.dev.azure.com/{organization}",
      "type": "http",
      "headers": {
        "X-MCP-Toolsets": "elm"
      }
    }
  },
  "inputs": []
}

Supported environments

The remote Azure DevOps MCP Server requires your user account and Azure DevOps organization to connect to Microsoft Entra ID.

Not all MCP clients support Microsoft Entra authentication by default. Some environments require extra steps to register the client application.

Supported environments for the remote endpoint, when Microsoft Entra authentication is available, include:

• Visual Studio with GitHub Copilot
• Visual Studio
• Microsoft Foundry
• Microsoft Copilot Studio
• GitHub Copilot CLI
• GitHub Copilot app
• Cursor desktop, Cursor Cloud Agents, or Claude Code with a custom Microsoft Entra app registration

Visual Studio Code

To configure the remote MCP Server in Visual Studio Code:

1. Add a .vscode/mcp.json file to your repository with the mcp.json configuration shown earlier.
2. Save the file.
3. Open GitHub Copilot in VS Code.
4. When prompted, authenticate by using your Microsoft Entra account and select your account.

After authentication completes, a list of available tools appears.

Visual Studio (2022 and later)

Configure the remote MCP Server in Visual Studio by adding the server URL to your MCP settings. For more information, see Use MCP servers in Visual Studio.

Choose OAuth scopes for custom clients

When you register a custom MCP client, grant only the delegated permissions required for the Azure DevOps operations that the client performs. OAuth scopes determine which Azure DevOps resources and operations the client can access. Enabling an MCP tool or toolset doesn't grant additional permissions.

Follow the principle of least privilege:

• Grant read scopes when the client uses only read-only MCP tools.
• Grant write or manage scopes only when the client needs the corresponding write operations.
• Review inherited scopes to avoid granting redundant permissions.

For the available scopes and their relationships, see OAuth scopes.

OAuth scopes don't override the permissions of the signed-in user. An MCP operation succeeds only when both the application scope and the user's Azure DevOps permissions allow it.

Cursor

Cursor requires a custom Microsoft Entra app registration to access the remote Azure DevOps MCP Server.

Register the application for Cursor desktop

1. Confirm that the Azure DevOps MCP enterprise application is provisioned in your tenant. If you can't find it, see Can't find the Azure DevOps MCP enterprise application in the tenant.
2. In the Microsoft Entra admin center, go to App registrations, and then create an app registration.
3. In the app registration, select Authentication (Preview) > Add redirect URI > Mobile and desktop applications.
4. Enter http://localhost:8787/callback as the redirect URI, and then save your changes.
5. On the Authentication (Preview) page, select the Settings tab, and then enable Allow public client flows.
6. On the API permissions page, select Add a permission > APIs my organization uses.
7. Search for Azure DevOps MCP or the application ID 2a72489c-aab2-4b65-b93a-a91edccf33b8, and then select the application.
8. Select the delegated permissions that your client requires, following the OAuth scope guidance, and then select Add permissions.
9. Select Grant admin consent. Depending on your role, a tenant administrator might need to complete this step.

Copy the Application (client) ID from the app registration. You need this value to configure Cursor.

Configure Cursor desktop

1. In Cursor, open Settings > Tools & MCP.

2. Select New MCP Server.

3. Add the following configuration, replacing {client-id} with the application (client) ID that you copied:

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

4. Save the configuration, and then return to Settings > Tools & MCP.

5. Locate the ado server, and then select Authenticate.

Configure Cursor Cloud Agents

Cursor Cloud Agents require a web redirect URI and a client secret in addition to the custom Microsoft Entra app registration.

1. In the Microsoft Entra admin center, open the app registration that you created for Cursor.

2. Select Authentication (Preview) > Add redirect URI > Web.

3. Enter https://www.cursor.com/agents/mcp/oauth/callback as the redirect URI, and then save your changes.

4. Select Certificates & secrets > Client secrets > New client secret.

5. Enter a description, select an expiration period, and then select Add.

6. Copy the client secret value. The value appears only once.

7. In Cursor, open the Cloud Agents MCP server configuration, and then add or edit the custom MCP server.

8. Set the server URL to https://mcp.dev.azure.com.

9. Enter the application (client) ID from your app registration in Client ID and the client secret value in Client Secret.

   Alternatively, edit the JSON configuration and replace the placeholders with your app registration values:

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

10. Save the configuration, and then select Log in from Cursor Cloud Agents to complete Microsoft Entra authentication.

If Microsoft Entra returns error AADSTS50011, verify that the web redirect URI exactly matches https://www.cursor.com/agents/mcp/oauth/callback. If token exchange fails with error AADSTS7000218, verify that the current client secret value is configured in Cursor Cloud Agents.

Claude Code

Claude Code requires a custom Microsoft Entra app registration to access the remote Azure DevOps MCP Server.

Register the application

1. Confirm that the Azure DevOps MCP enterprise application is provisioned in your tenant. If you can't find it, see Can't find the Azure DevOps MCP enterprise application in the tenant.
2. In the Microsoft Entra admin center, go to App registrations, and then create an app registration.
3. In the app registration, select Authentication (Preview) > Add redirect URI > Mobile and desktop applications.
4. Enter http://localhost:3118/callback as the redirect URI, and then save your changes.
5. On the Authentication (Preview) page, select the Settings tab, and then enable Allow public client flows.
6. On the API permissions page, select Add a permission > APIs my organization uses.
7. Search for Azure DevOps MCP or the application ID 2a72489c-aab2-4b65-b93a-a91edccf33b8, and then select the application.
8. Select the delegated permissions that your client requires, following the OAuth scope guidance, and then select Add permissions.
9. Select Grant admin consent. Depending on your role, a tenant administrator might need to complete this step.

Copy the Application (client) ID from the app registration. You need this value to configure Claude Code.

Configure Claude Code

1. Run the following command, replacing {client-id} with the application (client) ID that you copied and {organization} with your Azure DevOps organization name:

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

   Alternatively, create a .mcp.json file in the root of your repository with the following configuration:

   {
     "mcpServers": {
       "ado": {
         "type": "http",
         "url": "https://mcp.dev.azure.com/{organization}",
         "oauth": {
           "clientId": "{client-id}",
           "callbackPort": 3118
         }
       }
     }
   }
   

2. Start Claude Code by running claude.

3. Run /mcp, and then follow the browser sign-in flow to authenticate with your Microsoft Entra account.

For more information about these options, see Connect Claude Code to tools via MCP.

Verify the connection

After setup, verify the remote MCP Server is working by asking your AI assistant a question about your Azure DevOps data.

Examples:

• "List the projects in my Azure DevOps organization."
• "Show my assigned work items."
• "What pull requests require my review?"

If the AI assistant returns results from your Azure DevOps organization, the remote MCP Server is configured correctly.

Use AI to validate and troubleshoot remote MCP setup

The following example prompts for Copilot Chat help you choose the right MCP approach, configure and validate remote setup, improve day-to-day usage prompts, and troubleshoot failures when needed. Copy and paste these prompts into Copilot Chat, and replace placeholders with your actual organization, client, and error details.

Copilot is powered by AI, so surprises and mistakes are possible. For more information, see Copilot general use FAQs.

Troubleshooting

For support, you can create an issue in the local MCP Server repo. Be sure to use the Remote issue template.

FAQ

What about other clients like Claude Desktop or Codex?

Claude Desktop and Codex require dynamic registration of an OAuth client ID in Microsoft Entra ID before they can use the remote MCP Server. Microsoft Entra ID doesn't currently support the dynamic client registration flow that these clients require. Use the local MCP Server with these clients.

Related content

• Azure DevOps MCP Server overview
• Azure DevOps MCP Server GitHub repository