> For the complete documentation index, see [llms.txt](https://www.cakewalk.security/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.cakewalk.security/docs/ai-agent-access/connections-and-integrations/agent-connections/azure-devops-services.md). # Azure DevOps Services Connect your company's Azure DevOps organization to Cakewalk so agents can read work items, repositories, pipelines and wikis through the gateway. Connect your company's Azure DevOps organization to Cakewalk's MCP Gateway. Every agent tool call against Azure DevOps passes through the gateway and is evaluated against your Policies. ## Requirements * An Azure DevOps organization on `dev.azure.com`, backed by a Microsoft Entra tenant. Organizations on a standalone personal Microsoft account are not supported by Microsoft's MCP server. * A Microsoft Entra admin (Global Administrator or Application Administrator) for a one-time tenant step. Without it, setup stops at Step 1. * A user who can create app registrations in the same tenant. {% hint style="warning" %} This page covers Azure DevOps Services, the cloud product at `dev.azure.com`. Azure DevOps Server (the on-premises product, formerly TFS) has no MCP server, and Microsoft has stated support is not planned. It cannot be connected. {% endhint %} ## About Scopes Microsoft's MCP server exposes granular delegated scopes such as `wit.read` (work items), `repos.read`, `pipelines.read` and `wiki.read`, plus the base scope `Ado.Mcp.Tools`. The permissions you configure on the app registration in Step 3 are the scope set agents receive. Granting only read scopes keeps agents read-only; write scopes such as `wit.write` enable creating and updating. ## Step 1: Provision the Azure DevOps MCP Service Principal Microsoft's MCP service exists as an enterprise application that most tenants have never used, so its service principal is usually missing. This one-time step requires an Entra admin. 1. Open [Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer) and sign in with the admin account. 2. Set the method to **POST** and the URL to `https://graph.microsoft.com/v1.0/servicePrincipals`. 3. In **Request body**, enter: ```json { "appId": "2a72489c-aab2-4b65-b93a-a91edccf33b8" } ``` 4. Click **Run query**. 5. A **201 Created** response with `"displayName": "Azure DevOps MCP"` confirms the step. If you get **403 Insufficient privileges**, open the **Modify permissions** tab, consent to `Application.ReadWrite.All` and run the query again. 6. A **409 Conflict** response means the service principal already exists in your tenant. Nothing to fix; continue with Step 2. {% hint style="warning" %} Skipping this step causes two failures later: "Azure DevOps MCP" never appears in the API permission picker, and the connect flow fails with `AADSTS650057`. {% endhint %} ## Step 2: Register an App in Microsoft Entra 1. Open and go to **Microsoft Entra ID** > **App registrations** > **New registration**. 2. Name the app, for example `Cakewalk MCP Gateway`. 3. Under **Supported account types**, keep **Accounts in this organizational directory only**. 4. Under **Redirect URI**, select the **Web** platform and enter: ``` https://mcp-gateway.getcakewalk.io/api/v1/Auth/Callback ``` 5. Click **Register**. 6. On the app's **Overview** page, copy the **Application (client) ID**. This is Cakewalk's Client ID. ## Step 3: Configure API Permissions 1. In the app registration, open **API permissions** > **Add a permission**. 2. Switch to the **APIs my organization uses** tab and search for **Azure DevOps MCP**. It appears only after Step 1. 3. Select **Delegated permissions** and check `Ado.Mcp.Tools` plus the scopes matching the agent actions you want to allow. A read-only start: `wit.read`, `repos.read`, `pipelines.read`, `work.read`, `wiki.read`. 4. Click **Add permissions**. 5. If an Entra admin is available, click **Grant admin consent**. Otherwise the connecting user approves the same scopes on a consent screen during Step 6; these permissions allow user consent by default. Adding permissions works for any owner of the app registration. Only the **Grant admin consent** button requires an admin role. ## Step 4: Create a Client Secret 1. In the app registration, open **Certificates & secrets** > **New client secret**. 2. Add a description and an expiry, then click **Add**. 3. Copy the **Value** column immediately. Azure shows it once and masks it after you leave the page. {% hint style="warning" %} Copy **Value**, not **Secret ID**. The Secret ID is a GUID that looks like a credential but is not one. Pasting it into Cakewalk fails silently: the Microsoft sign-in completes and the Connection still does not activate. {% endhint %} The Value is Cakewalk's Client Secret. ## Step 5: Paste Credentials Into Cakewalk 1. Open . 2. Go to All Connections. 3. Find Azure DevOps. 4. Click Edit credentials. 5. Paste the Application (client) ID as **Client ID** and the secret Value as **Client Secret**. 6. Enter your organization's MCP URL: `https://mcp.dev.azure.com/{organization}`, where `{organization}` is the name in your `dev.azure.com/{organization}` address. 7. Save. ## Step 6: Approve Scopes on Consent Trigger the OAuth flow from Cakewalk. Microsoft presents a sign-in followed by a consent screen listing the permissions configured in Step 3. Review and approve. If an admin already granted consent in Step 3, the consent screen is skipped. ## Verifying It Works The Azure DevOps Connection card flips to Active on All Connections. From an agent platform connected to Cakewalk, start a new agent session and ask the agent to list work items from one of your projects. If Azure DevOps returns results, the Connection is live. {% hint style="info" %} Agent sessions that were already running before the Connection went live may not see the new Azure DevOps tools. Start a fresh session. {% endhint %} ## Troubleshooting * `AADSTS650057` (invalid resource) during sign-in: Step 1 was skipped or Step 3 permissions are missing. Provision the service principal, add the **Azure DevOps MCP** permissions, then reconnect. * `AADSTS700016` (application not found): the Client ID in Cakewalk does not match the app registration. Re-check the credentials after every edit of the Connection; re-paste the Application (client) ID from the app's Overview page. * Sign-in completes but the Connection stays inactive: the Client Secret is wrong, usually the Secret ID instead of the Value. Create a new secret, copy the Value and re-paste it. * **Grant admin consent** is grayed out: your account lacks an Entra admin role. Proceed without it; the consent screen in Step 6 covers these permissions. An admin can grant tenant-wide consent later. * **Azure DevOps MCP** missing from the API picker: the service principal does not exist in the tenant. Repeat Step 1 with an admin account. The `adminconsent` URL shortcut does not work for this app; use the Graph Explorer method. * Organization not accepted: confirm the organization is Entra-backed under **Organization settings** > **Microsoft Entra** in Azure DevOps. Standalone Microsoft-account organizations are not supported by Microsoft's MCP server. ## Learn More * [Azure DevOps MCP Server overview](https://learn.microsoft.com/en-us/azure/devops/mcp-server/mcp-server-overview) * [Set up the remote Azure DevOps MCP Server](https://learn.microsoft.com/en-us/azure/devops/mcp-server/remote-mcp-server) * [microsoft/azure-devops-mcp on GitHub](https://github.com/microsoft/azure-devops-mcp) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://www.cakewalk.security/docs/ai-agent-access/connections-and-integrations/agent-connections/azure-devops-services.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.