Azure DevOps Advanced MCP
Connect Azure DevOps Services to QuilrAI through the custom Azure DevOps Advanced MCP. It provides 47 model-facing tools across organizations, projects, Azure Repos, pull requests, Boards, Pipelines, Test Plans, Wiki, Search, and Advanced Security.
The integration uses Microsoft Entra delegated OAuth. Each user signs in with their own Microsoft account, and Azure DevOps applies that user's existing organization, project, repository, pipeline, and work-item permissions.
MCP client -> QuilrAI Gateway -> Azure DevOps MCP -> Microsoft Entra -> Azure DevOps
This guide covers cloud-hosted Azure DevOps Services at dev.azure.com. It does
not cover Azure DevOps Server hosted on a customer's own network.
See Provider Setup Overview for shared prerequisites and secret handling.
Authentication Model
The custom MCP uses a pre-registered Microsoft Entra application and delegated
user_impersonation permission for the Azure DevOps resource. It does not use
the deprecated Azure DevOps OAuth application registration system.
Microsoft stopped accepting new Azure DevOps OAuth registrations in April 2025 and recommends Microsoft Entra OAuth for new integrations. Do not create a legacy application through the old Azure DevOps OAuth registration page.
Create The Microsoft Entra Application
If QuilrAI already provides a managed Entra application for your tenant, skip this section and ask the tenant administrator to approve that application. Otherwise, create a customer-owned application:
-
Sign in to the Microsoft Entra admin center using an account allowed to manage application registrations.
-
Open Entra ID > App registrations and select New registration.
-
Enter a recognizable name, such as
QuilrAI Azure DevOps MCP. -
Choose the supported account type:
- Select Accounts in this organizational directory only for a dedicated single-tenant customer deployment.
- Select Accounts in any organizational directory only for an approved multi-tenant deployment.
-
Under Redirect URI, select Web and enter:
https://azure-devops.mcp.quilr.ai/auth/callback -
Select Register.
-
From Overview, copy:
- Application (client) ID
- Directory (tenant) ID, or use
organizationsonly for an approved multi-tenant application
-
Open API permissions and select Add a permission.
-
Select APIs my organization uses, search for Azure DevOps, and select it.
-
Select Delegated permissions, enable
user_impersonation, and add the permission. -
Grant tenant-wide admin consent if your organization's consent policy requires it. Otherwise, users are prompted during connection.
-
Open Certificates & secrets > Client secrets and select New client secret.
-
Choose an approved description and expiration, then select Add.
-
Copy the secret Value immediately. Do not copy the Secret ID.
Microsoft displays the Client Secret value only once. Store it in the approved secret manager and provide it to the QuilrAI operator through the authorized onboarding channel. Never place it in an MCP client JSON file, browser chat, ticket, source repository, or the gateway transport URL.
The service requests these OAuth scopes:
499b84ac-1321-427f-aa17-267ca6975798/user_impersonation
openid
profile
offline_access
499b84ac-1321-427f-aa17-267ca6975798 is the Azure DevOps resource identifier.
The application receives delegated access, not unrestricted application access.
The signed-in user's Azure DevOps permissions remain the effective boundary.
Azure DevOps Prerequisites
Before users connect, confirm that:
- the Azure DevOps organization is connected to the intended Microsoft Entra tenant;
- each user is a member or guest of every Azure DevOps organization they need;
- users have project and resource permissions for the tools they will invoke;
- Advanced Security is enabled and licensed where security tools are required;
- Test Plans, Pipelines, Wiki, and other product features are enabled where relevant;
- tenant consent and Conditional Access policies permit the Entra application;
- destructive tools are denied in QuilrAI unless separately approved.
Add The MCP To QuilrAI
-
In QuilrAI, go to Settings > AI Gateway > MCP Gateway.
-
Click Add MCP.
-
Enter the following values:
-
Create the MCP connection.
-
Click Connect or Reconnect.
-
Sign in with the Microsoft identity that has access to the required Azure DevOps organization and accept the requested permissions.
-
Return to QuilrAI and refresh capabilities. The MCP should expose 47 tools.
-
Use Tools, Access Control, Guardrails, and group/user rules to restrict the exposed operations before connecting agent clients.
Do not enter the Entra Client Secret into Cursor, Claude, ChatGPT, or another MCP client. The upstream MCP service owns the Entra application configuration.
Organization Selection
An Azure DevOps user can belong to one or several organizations. Organization arguments are optional on normal organization-scoped tools:
- With one linked organization, the MCP selects and saves it automatically.
- With multiple organizations and no saved selection, a tool returns
organization_selection_requiredwith the available choices. - Call
ado_select_organizationusing the exact URL-name segment, such ascontosofromhttps://dev.azure.com/contoso. - Do not pass a full URL or a display label.
- An organization supplied directly to another tool is a one-call override and does not silently replace the saved selection.
Organization discovery and the selected organization are stored per signed-in principal. Access and refresh tokens are not stored in the organization-context file.
Tool Catalog
The 47 tools are grouped by risk and usage style. Direct tools cover frequent
operations with explicit schemas. Dispatcher tools consolidate related
operations behind an action selector. Intelligence tools combine several API
calls into one useful briefing. Destructive tools always require an exact
confirmation phrase.
Organization and common direct tools
Compatibility dispatcher tools
Intelligence tools
Destructive tools
These tools are marked destructive, are not retried automatically, and reject the request unless the exact confirmation value is supplied. Keep them disabled in QuilrAI unless the customer has explicitly approved the workflow.
Connect An MCP Client
Use the generated QuilrAI gateway URL. Do not point the agent directly at the private upstream URL.
Cursor example:
{
"mcpServers": {
"ado": {
"type": "http",
"url": "https://mcpgateway.quilr.ai/YOUR-AZURE-DEVOPS-SLUG/mcp"
}
}
}
Use a short key such as ado to keep combined server/tool names compact. For
Claude, add a custom connector with the same generated QuilrAI gateway URL and
leave the optional OAuth Client ID and Client Secret fields empty.
Verify The Connection
Start with a discovery-only prompt:
Use the Azure DevOps MCP. First call ado_list_organizations. If there is one
organization, use it automatically. If there are multiple, show me the choices
and wait for my selection. Then list the first 20 projects. Do not guess an
organization and do not create, update, run, vote, comment, or delete anything.
After selecting a project, test a bounded read:
Using my selected Azure DevOps organization, list repositories in PROJECT_NAME,
then show active pull requests for the first repository. Read-only operations
only.
Redeployment And Reconnection
Routine MCP redeployments should not require users to authenticate again when all of the following remain stable:
- the public MCP URL and OAuth callback URL;
- the Entra tenant and Application ID;
- the MCP OAuth JWT signing key;
- the encrypted OAuth state volume;
- the organization-context state volume.
Users normally need to reconnect after the Entra Client Secret expires or is rotated without updating the service, consent is revoked, required scopes change, refresh fails permanently, OAuth state is lost, the public resource URL changes, or the Entra application is replaced.
Organization membership is refreshed automatically. A routine restart can refresh linked organizations without requiring the user to sign in again.
Troubleshooting
Security Notes
- Prefer Microsoft Entra OAuth over personal access tokens.
- Do not request or store a user's Microsoft password. Sign-in occurs only on Microsoft-hosted pages.
- Never expose the Entra Client Secret, access tokens, refresh tokens, PATs, or OAuth signing key in agent configuration or logs.
- Apply least privilege in Azure DevOps and again through QuilrAI tool and group policies.
- Keep write and destructive operations disabled unless they are required and approved.
- Review the exact organization, project, repository, branch, work item, build, or pipeline before approving a destructive action.