# Azure DevOps

Microsoft hosts the remote Azure DevOps MCP server. It gives each person's MCP client tools for work items, repositories, pull requests, pipelines, wikis, test plans, and advanced security in one Azure DevOps organization. Each person signs in with their own Microsoft Entra account. A call succeeds only when both the permissions you grant the application and that person's own Azure DevOps permissions allow it.

You need an Azure DevOps Services organization that is backed by a Microsoft Entra tenant; organizations that use standalone Microsoft accounts are not supported. Note the organization name, for example `contoso` from `https://dev.azure.com/contoso`. An Entra administrator registers one application in that tenant and grants admin consent once. Each person who connects needs membership in the projects they will use. Keep the client secret out of source control, screenshots, and support transcripts.

### Confirm the Azure DevOps MCP application
<!-- screenshot: Enterprise applications search showing Azure DevOps MCP with Application type set to All applications; tenant name redacted -->

Microsoft's Azure DevOps MCP application must exist in your tenant before you can grant permissions to it.

1. In the [Azure portal](https://portal.azure.com), open **Microsoft Entra ID > Enterprise applications**.
2. Set **Application type** to **All applications**.
3. Search for **Azure DevOps MCP** or this application ID:

   ```text
   2a72489c-aab2-4b65-b93a-a91edccf33b8
   ```

If it is listed, continue to the next section. If it is not, an Application Administrator, Cloud Application Administrator, or Global Administrator creates it with the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli), replacing `` with your tenant ID:

```text
az login --tenant <TENANT_ID> --allow-no-subscriptions
az ad sp create --id 2a72489c-aab2-4b65-b93a-a91edccf33b8
```

Then search again. See Microsoft's [troubleshooting steps](https://learn.microsoft.com/en-us/azure/devops/mcp-server/remote-mcp-server-troubleshooting?view=azure-devops#cant-find-the-azure-devops-mcp-enterprise-application-in-the-tenant) for how to check the result.

### Register the Entra application
<!-- screenshot: Entra app registration with "Accounts in this organizational directory only" and a Web redirect URI; tenant and client identifiers redacted -->

In the [Microsoft Entra admin center](https://entra.microsoft.com), open **App registrations** and select **New registration**. See Microsoft's [app registration guide](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).

1. Enter a name, for example **Speakeasy Azure DevOps MCP**.
2. Under **Supported account types**, select **Accounts in this organizational directory only**.
3. Under **Redirect URI**, select the **Web** platform and enter the callback for your Speakeasy deployment:

   ```text
   https://ai.speakeasy.com/mcp/remote_login_callback
   ```

   Use this exact value. Do not use the localhost callbacks from Microsoft's Cursor or Claude Code instructions.

4. Select **Register**.
5. On the app's **Overview**, record the **Application (client) ID** and the **Directory (tenant) ID**. The object ID is not the client ID.

Leave **Allow public client flows** off. Microsoft's Cursor desktop instructions turn it on, but Speakeasy signs in with a client secret instead.

### Add the Azure DevOps MCP permissions
<!-- screenshot: API permissions list with Azure DevOps MCP delegated permissions and admin consent granted; tenant name redacted -->

1. In the app, open **API permissions** and select **Add a permission**.
2. Select **APIs my organization uses**, then search for **Azure DevOps MCP** or the application ID from [Confirm the Azure DevOps MCP application](#confirm-enterprise-application), and select it.
3. Select the delegated permissions for the work people will do, then select **Add permissions**.
4. Select **Grant admin consent** for your tenant and confirm. Depending on your role, a tenant administrator might need to do this.

Grant only what people need. Choose read permissions if they only read, and add write or manage permissions only for the operations that need them. Some permissions include others, so avoid adding both. Microsoft's [OAuth scopes reference](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=azure-devops#oauth-scopes) lists what each one grants. Turning on more MCP tools later does not widen these permissions.

### Create a client secret
<!-- screenshot: Certificates & secrets with a new client secret; the secret value redacted -->

**Before you start:** Entra shows the secret **Value** only once. Have your approved password manager ready.

1. In the app, open **Certificates & secrets** and select **New client secret**.
2. Enter a description and choose an approved expiry.
3. Select **Add**, then copy the **Value**, not the **Secret ID**, into your password manager.

Record the expiry date and assign an owner. Sign-in stops working when the secret expires, so create a replacement beforehand and update the client in Speakeasy.

### Add the server in Speakeasy
1. In the Speakeasy AI Control Plane sidebar, under **MCP Gateway**, select **MCP**.
2. Click **Add new** to open **Add MCP server**.
3. Choose **Hosted remotely**.
4. On **New remote MCP server**, paste this into **MCP server URL**, replacing `` with your Azure DevOps organization name, for example `contoso`:

   ```text
   https://mcp.dev.azure.com/<organization>
   ```

   Use the organization name only, not the full `dev.azure.com` address.

5. Optionally enter **Display name (optional)**, for example **Azure DevOps**.
6. Leave **User session issuer** at its default.
7. Click **Verify connectivity**. The server answers with a sign-in challenge, so **Identity** preselects **User Identity**. Keep it selected.
8. Leave **Guardrails** off unless your organization requires one, then click **Save**.

Speakeasy is expected to report that the server was added but kept disabled, and to open the server's **Settings** at the identity section. Microsoft does not support automatic client registration, so the client from [Register the Entra application](#register-entra-application) is added by hand below.

<!-- screenshot: New remote MCP server with the Azure DevOps URL and User Identity selected; organization name redacted -->

### Connect your credentials
The server's metadata names Microsoft's multi-tenant sign-in address (`https://login.microsoftonline.com/organizations/v2.0`). Its published issuer is a placeholder, so Speakeasy cannot discover it as named. Point the new authorization server at your own tenant instead.

1. In the server's **Settings > Identity**, confirm **User Identity** is selected.
2. Under the authorization server badged **Will be created**, find the error that the metadata document advertises a different issuer than the one requested, and the **Issuer URL** field below it.
3. Replace the **Issuer URL** value with the following, replacing `` with the **Directory (tenant) ID** from [Register the Entra application](#register-entra-application):

   ```text
   https://login.microsoftonline.com/<TENANT_ID>/v2.0
   ```

4. Click **Discover** and wait for "OAuth metadata discovered. Save to finish setup."
5. Choose **Manual**.
6. Paste the **Application (client) ID** into **Client ID**.
7. Paste the secret **Value** from [Create a client secret](#create-client-secret) into **Client secret**. Microsoft requires the secret despite the field's "Optional" placeholder.
8. Open **Advanced**. In **Scope**, select or type each of these values:

   ```text
   offline_access
   https://mcp.dev.azure.com/.default
   ```

   The `offline_access` scope allows Speakeasy to refresh access tokens. The `.default` value requests the permissions you consented in [Add the Azure DevOps MCP permissions](#add-azure-devops-permissions).

9. In **Audience**, enter:

   ```text
   https://mcp.dev.azure.com
   ```

10. Click **Save**. If prompted, confirm with **Save changes**.
11. Open **Settings > Danger Zone > Server Availability** and turn on **Enable MCP server** so it shows **Enabled**.

If the picker preselects an existing Microsoft authorization server instead and no **Issuer URL** field appears, check its address. Keep it if it is your tenant address from step 3, and continue from step 5. Otherwise, open the picker and choose your tenant's authorization server. If none is listed, an organization admin clicks **Create a custom authorization server**, clicks **New Authorization Server**, enters your tenant address in **Issuer URL**, clicks **Discover**, then clicks **Create**. Return to **Settings > Identity**, choose the new authorization server, and continue from step 5.

The first time each person uses the server, Microsoft's sign-in page appears in their browser. They sign in with their own work account.

If sign-in fails, Entra shows an `AADSTS` error code:

- `AADSTS50011`: the **Web** redirect URI does not exactly match the callback in [Register the Entra application](#register-entra-application).
- `AADSTS7000218` or `invalid_client`: check the **Client ID**, and that the secret **Value** is current and not the **Secret ID**.
- `AADSTS65001`: admin consent was not granted in [Add the Azure DevOps MCP permissions](#add-azure-devops-permissions).
- `AADSTS700016`: check that the tenant ID in the **Issuer URL** is the tenant where you registered the application.

If sign-in fails with an error about the `resource` parameter, ask your Speakeasy administrator to stop sending the resource indicator for this authorization server. If tools return no data, check that the person is a member of the project and has access to the resources they asked about.

<!-- screenshot: Settings > Identity with User Identity, the corrected tenant Issuer URL, and Manual selected; values redacted -->

This guide covers setup only. For anything beyond it, such as tools, toolsets, and limits, see [Microsoft's Azure DevOps MCP Server documentation](https://learn.microsoft.com/en-us/azure/devops/mcp-server/remote-mcp-server?view=azure-devops).

---

Index of every Speakeasy page for agents: [llms.txt](https://www.speakeasy.com/llms.txt). AI control plane and MCP gateway content in one file: [llms-full.txt](https://www.speakeasy.com/llms-full.txt). Any page is available as markdown by appending `.md` to its URL or by requesting it with `Accept: text/markdown`.
