Skip to content
Status

Azure DevOps

Connect the Speakeasy AI Control Plane to Microsoft's hosted Azure DevOps MCP server with a single-tenant Entra application for delegated user access.

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

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

  1. In the Azure portal, open Microsoft Entra ID > Enterprise applications.

  2. Set Application type to All applications.

  3. Search for Azure DevOps MCP or this application ID:

    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, replacing <TENANT_ID> with your tenant ID:

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 for how to check the result.

Register the Entra application

In the Microsoft Entra admin center, open App registrations and select New registration. See Microsoft’s app registration guide.

  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:

    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

  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, 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 lists what each one grants. Turning on more MCP tools later does not widen these permissions.

Create a client secret

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 <organization> with your Azure DevOps organization name, for example contoso:

    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 is added by hand below.

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 <TENANT_ID> with the Directory (tenant) ID from Register the Entra application:

    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 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:

    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.

  9. In Audience, enter:

    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.
  • 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.
  • 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.

This guide covers setup only. For anything beyond it, such as tools, toolsets, and limits, see Microsoft’s Azure DevOps MCP Server documentation.