Skip to main content

Azure DevOps

Azure DevOps Services is Microsoft's hosted platform for source control (Azure Repos), work tracking (Azure Boards), CI/CD (Azure Pipelines), documentation (Azure DevOps Wiki), and test management (Azure Test Plans). This connector covers all five through the Azure DevOps REST API, so an AI client can read a repository, open a pull request, triage work items, inspect a failing build's logs, and update a runbook without leaving the conversation.

This connector targets Azure DevOps Services (dev.azure.com). Azure DevOps Server, the on-premises product, is not supported: it has no OAuth support and its API surface differs.

Configuration​

Two settings live on the connector's Setup tab, alongside the auth fields:

SettingRequiredDescription
OrganizationYesYour organization name — the segment after dev.azure.com/. For https://dev.azure.com/contoso this is contoso.
Default ProjectNoUsed whenever a tool call omits the project argument. Set this if the server should work in one project, so agents do not have to name it on every call.

Every tool also accepts an explicit project argument, which overrides the default. Leave Default Project empty when you want the server to span several projects.

Authentication Types​

  • OAuth - Register your own app in Microsoft Entra ID and have each user authorize with their Microsoft account.
    • Pros: per-user access and audit trail, granular vso.* scopes, automatic token refresh, no long-lived secret to rotate
    • Cons: needs an Entra ID app registration and, usually, an admin to grant consent
  • API Key - One personal access token (PAT) shared by everyone using the server.
    • Pros: fastest setup, works without an Entra ID app
    • Cons: every action is attributed to the token's owner, and PATs expire and must be rotated by hand
  • API Key (per user) - Each user supplies their own PAT.
    • Pros: per-user attribution without an app registration
    • Cons: each person has to create and later rotate their own token

OAuth is the right default for production. Microsoft deprecated Azure DevOps OAuth and stopped accepting new app registrations in April 2025, so this connector uses Microsoft Entra ID OAuth instead — the same identity platform the Outlook and SharePoint connectors use.

Setting up OAuth​

Register the app in Entra ID​

  1. Go to the Azure Portal and open Microsoft Entra ID > App registrations > New registration.
  2. Give the app a name, for example "Willow Azure DevOps Integration".
  3. Under Supported account types, choose Accounts in any organizational directory if users from more than one tenant will connect, or single-tenant if not.
  4. Under Redirect URI, choose platform Web and paste the redirect URL Willow shows on the connector's Setup tab. Copy it from Willow rather than typing it; Entra ID rejects the authorization if it does not match exactly.
    • SaaS deployments: https://{org}.mcp-s.com/{org}/api/auth/callback
    • On-premise deployments: {connectUrl}/{org}/api/auth/callback
  5. Select Register.

Grant the Azure DevOps permissions​

  1. In the app registration, open API permissions > Add a permission.
  2. Select the APIs my organization uses tab and search for Azure DevOps.
  3. Choose Delegated permissions and add the vso.* permissions your enabled tools need. See the table below.
  4. Select Grant admin consent for [your tenant] if you have the rights. Without consent, users hit AADSTS65001 on their first connection.
tip

Azure DevOps has a fixed resource identifier, 499b84ac-1321-427f-aa17-267ca6975798. Entra ID rejects bare scopes like vso.code, so the connector requests them fully qualified as 499b84ac-.../vso.code. That is handled for you — just pick the scope names in Willow.

Create a client secret​

  1. Open Certificates & secrets > New client secret.
  2. Add a description and choose an expiration.
  3. Copy the secret Value immediately. It is shown only once.

Enable third-party access in Azure DevOps​

In your Azure DevOps organization, open Organization settings > Microsoft Entra and make sure Third-party application access via OAuth is enabled. When it is off, tokens are issued successfully but every API call comes back 203 Non-Authoritative Information with an HTML sign-in page instead of JSON.

Configure it in Willow​

  1. In Willow, open Build > MCP Servers > Add MCP Server, search for Azure DevOps, and select Use.
  2. Review the risk level and tool list, then select Create.
  3. On the server's Setup tab, choose OAuth.
  4. Paste the Application (client) ID and the client secret.
  5. Select the same scopes you granted in Entra ID, plus offline_access — without it Entra ID issues no refresh token and users have to reconnect every hour.
  6. Enter your Organization and, optionally, a Default Project, then select Save Changes.
  7. Each user connects from the MCP Gateway and authorizes with their Microsoft account.

Generating a personal access token​

Use a PAT when you want to skip the app registration, or for a service-account style setup.

  1. Go to dev.azure.com and open User settings (top right) > Personal access tokens.
  2. Select New Token.
  3. Pick the organization, set an expiration, and select the scopes you need: Code, Work Items, Build, Wiki, Test Management, and so on.
  4. Select Create and copy the token — it is shown only once.
  5. In Willow, choose API Key (shared) or API Key (per user) on the Setup tab and paste the token. Paste the token only, with no username and no colon; Willow wraps it in the HTTP Basic header Azure DevOps expects.
warning

A PAT carries its owner's permissions, and Azure DevOps records every action under that identity. For shared servers, create the token from a dedicated service account rather than a person's account, and set a calendar reminder before the expiry date.

Scopes each tool group needs​

Grant only what your enabled tools require. Azure DevOps scopes inherit, so vso.code_write already includes everything vso.code allows.

ToolsAzure DevOps scope
List Projects, List Project Teams, List Work Item Typesvso.project
List Repositories, Get Repository, List Branches, Get File, List Repository Items, Search Commits, List Pull Requests, Get Pull Request, List Pull Request Threads, List Pull Request Work Items, Search Codevso.code
Create Branch, Create Pull Request, Update Pull Request, Set Pull Request Votevso.code_write
Create Pull Request Thread, Reply To Pull Request Thread, Update Pull Request Thread Statusvso.threads_full
List Pipelines, Get Pipeline, List Pipeline Runs, Get Pipeline Run, List Build Definitions, List Builds, Get Build, List Build Logs, Get Build Log Content, List Build Artifactsvso.build
Run Pipeline, Cancel Buildvso.build_execute
Get Work Item, Get Work Items Batch, List Work Item Comments, Run Work Item Query, List Saved Queries, List Backlogs, List Backlog Work Items, List Team Iterations, List Iteration Work Items, Get Team Capacity, Search Work Itemsvso.work
Create Work Item, Update Work Item, Add Work Item Comment, Link Work Items, Upload Work Item Attachment, Add Work Item Attachment Link, Assign Team Iteration, Update Team Member Capacityvso.work_write
List Wikis, Get Wiki, Get Wiki Page, Search Wikivso.wiki
Create Or Update Wiki Pagevso.wiki_write
List Test Plans, List Test Suites, List Test Cases, List Test Runs, Get Test Run, List Test Results, Get Test Results From Buildvso.test
Create Test Plan, Create Test Suite, Add Test Cases To Suite, Create Test Run, Update Test Runvso.test_write
List Advanced Security Alerts, Get Advanced Security Alertvso.advsec

The connector also offers 499b84ac-.../.default, which grants every delegated permission configured on the app registration. Entra ID rejects .default when it is combined with granular scopes for the same resource, so select it on its own (alongside offline_access) or not at all.

Microsoft maintains the authoritative list, including scopes for packaging, service connections, and notifications that this connector does not use. See Azure DevOps OAuth scopes.

Available Tools​

The connector exposes 71 tools: 48 read-only, 20 that write, and 3 classified high risk.

Projects and teams​

List Projects, List Project Teams, List Work Item Types

Start with List Projects to discover project names. List Work Item Types is worth calling before creating work items, since valid types and states depend on the project's process template.

Repositories and files​

List Repositories, Get Repository, List Branches, Create Branch, Get File, List Repository Items, Search Commits

List Repository Items browses the file tree without content, which is the cheap way to explore a repository before reading specific files with Get File. Create Branch needs a source commit SHA — take the objectId of the source branch from List Branches.

Pull requests​

List Pull Requests, Get Pull Request, Create Pull Request, Update Pull Request, List Pull Request Threads, Create Pull Request Thread, Reply To Pull Request Thread, Update Pull Request Thread Status, Set Pull Request Vote, List Pull Request Work Items

Create Pull Request Thread leaves an inline code comment when you pass a file path and line range, and a general comment when you do not. Update Pull Request doubles as the merge and abandon action: set status to completed to merge or abandoned to close.

Pipelines and builds​

List Pipelines, Get Pipeline, Run Pipeline, List Pipeline Runs, Get Pipeline Run, List Build Definitions, List Builds, Get Build, Cancel Build, List Build Logs, Get Build Log Content, List Build Artifacts

For debugging a red build: List Builds filtered to resultFilter: failed, then List Build Logs, then Get Build Log Content with a line range so you fetch the tail rather than the whole log. Run Pipeline accepts preview_run: true to validate the expanded YAML without queueing anything.

Work items​

Get Work Item, Get Work Items Batch, Create Work Item, Update Work Item, List Work Item Comments, Add Work Item Comment, Link Work Items, Upload Work Item Attachment, Add Work Item Attachment Link, Run Work Item Query, List Saved Queries, List Backlogs, List Backlog Work Items

Run Work Item Query takes WIQL, Azure Boards' SQL-like query language, and returns IDs only; follow it with Get Work Items Batch to read fields for up to 200 items in a single call. Update Work Item only touches the fields you pass, so it is safe to use for a single state change. Attaching a file is two steps: Upload Work Item Attachment returns a URL, then Add Work Item Attachment Link attaches it.

Boards, iterations, and capacity​

List Team Iterations, Assign Team Iteration, List Iteration Work Items, Get Team Capacity, Update Team Member Capacity

These are team-scoped, so they need a team argument from List Project Teams. Pass timeframe: current to List Team Iterations to find the sprint in progress.

Wiki​

List Wikis, Get Wiki, Get Wiki Page, Create Or Update Wiki Page

Create Or Update Wiki Page replaces a page's full content rather than merging into it. Creating a new page needs nothing extra, but updating an existing one requires the page's ETag as the version argument — read it from Get Wiki Page first. That is Azure DevOps preventing you from silently overwriting a concurrent edit.

Search Code, Search Work Items, Search Wiki

Code search supports element filters in the query text, such as class:PaymentService or func:handleWebhook. Use Search Work Items for fuzzy text matching and Run Work Item Query when you need precise field-based filtering.

Test management​

List Test Plans, Create Test Plan, List Test Suites, Create Test Suite, List Test Cases, Add Test Cases To Suite, List Test Runs, Get Test Run, List Test Results, Get Test Results From Build, Create Test Run, Update Test Run

Get Test Results From Build returns the aggregate pass/fail summary for a build, which answers "did the tests pass" without paging through individual results. Test cases are work items, so create one with Create Work Item using the Test Case type and then add it with Add Test Cases To Suite.

Advanced Security​

List Advanced Security Alerts, Get Advanced Security Alert

These surface secret-scanning, dependency-scanning, and code-scanning findings. They require GitHub Advanced Security for Azure DevOps to be enabled on the repository and the vso.advsec scope; without it, calls return 404.

High-risk tools​

Three tools are classified high risk and are excluded at the default Medium Risk level:

  • Update Pull Request — can merge or abandon a pull request, changing the target branch's contents
  • Set Pull Request Vote — approving can satisfy branch policies and let code merge into a protected branch
  • Run Pipeline — executes pipeline code, which may deploy to production

Enable them deliberately, and consider requiring approval per call. See Manage tools.

Troubleshooting​

Every call returns 203 Non-Authoritative Information or an HTML page. The token is valid but Azure DevOps is refusing third-party OAuth access. Enable Third-party application access via OAuth in Organization settings > Microsoft Entra.

AADSTS65001: The user or administrator has not consented. The Entra ID app has not been granted the delegated Azure DevOps permissions. Add them under API permissions and select Grant admin consent, or reduce the requested scopes to ones the user can consent to themselves.

invalid_scope during authorization. A scope was sent without the Azure DevOps resource prefix. This should not happen through Willow; if you edited the scope list manually, make sure each vso.* entry is prefixed with 499b84ac-1321-427f-aa17-267ca6975798/, and that .default is not mixed with granular scopes.

Users are asked to reconnect every hour. offline_access is missing from the selected scopes, so Entra ID never issued a refresh token. Add it and have users reconnect.

A tool returns 401 after working for weeks. On PAT auth, the token expired. Azure DevOps PATs have a maximum lifetime and cannot be renewed silently — create a new one and update the connector.

TF400813: The user is not authorized to access this resource. Access is evaluated against the connecting user's Azure DevOps permissions, not the app's. Check that the person is a member of the organization and has access to the project in question.

Work item create fails with a rules error. The project's process requires fields this call did not set, or the state is invalid for the type. Call List Work Item Types to see the type's fields and states, and pass extras through the fields argument.

Advanced Security tools return 404. Advanced Security is not enabled on that repository, or the token is missing vso.advsec.

A wiki page update fails with 409 or "version required". Create Or Update Wiki Page needs the current page's ETag when replacing an existing page. Call Get Wiki Page and pass its ETag as version.

Limitations​

  • Azure DevOps Services only. Azure DevOps Server (on-premises) is not supported.
  • Microsoft account (MSA) users. Entra ID apps do not natively support MSA identities for the Azure DevOps resource. Organizations backed by Microsoft accounts rather than Entra ID should use PAT authentication.
  • Attachments are text-only. Upload Work Item Attachment sends the content you pass as a string, so binary files are out of scope.
  • Search requires indexing. Code, work item, and wiki search only return results from branches and projects Azure DevOps has indexed. Newly pushed branches take a few minutes to appear.
  • Rate limiting. Azure DevOps throttles by consumption units per organization and returns 429 with a Retry-After header. The connector does not retry automatically.
  • No release pipelines. The classic Releases API is not covered; use Run Pipeline with a YAML pipeline instead.

Additional Resources​

On this page