AzDO MCP — Azure DevOps for AI Assistants

by Babylon's Factor

Give Claude Code, Copilot Chat, Cursor, and any MCP-compatible AI the ability to read and write your Azure DevOps boards, repos, pipelines, and wikis — through a single extension install and bearer token.

What this extension does

AzDO MCP bridges VS Code and its AI clients to the AzDO MCP Gateway — a secure, per-developer proxy that sits between your AI and Azure DevOps. The extension handles two things:

Connection — auto-writes the gateway URL + bearer token into VS Code MCP settings and ~/.claude.json so Claude Code, Copilot, and Cursor immediately find the server. Zero JSON editing.
Process configuration — a wizard that lets you declare which work item types and fields the AI can access, generating a .azdo-mcp.json file you commit to your repo. The gateway enforces these rules server-side on every API call.

Quick start

1 — Get a token

Sign up at https://51-15-214-19.nip.io and choose a plan.
In the portal, go to the AzDO MCP tab → Add organisation.
Enter a label, your Azure DevOps org URL (https://dev.azure.com/yourorg), and a Personal Access Token you generate in your AzDO org settings.
The portal validates the PAT and returns your gateway Bearer token — copy it and save it somewhere safe. It is only shown once.

PAT scopes needed: vso.work + vso.work_write + vso.project for Boards; add vso.code + vso.code_status for Developer; add vso.build + vso.build_execute for Admin. When testing, start with Full access scoped to your org and narrow later.

2 — Install the extension

Search "AzDO MCP" in the Extensions panel (Ctrl+Shift+X), or install from the VS Marketplace page.

3 — Open the configure panel

Open the Command Palette (Ctrl+Shift+P) → AzDO MCP: Configure

The configure panel opens as a webview:

Toggle SaaS or Self-Hosted mode
For SaaS: paste your bearer token (gateway URL is pre-filled)
For Self-Hosted: enter your gateway URL (e.g. http://localhost:9004/mcp) and optional token
Click Test Connection — live result shown inline; on success, your AzDO projects load as checkboxes
Optionally check Project Scope boxes to limit which projects the AI can access
Click Save — MCP config is written to VS Code settings and ~/.claude.json automatically

You will see: "AzDO MCP configured — Claude Code and VS Code MCP clients are now connected."

4 — Configure process and field access (optional, recommended for teams)

Command Palette → AzDO MCP: Configure Process & Work Items

This wizard:

Fetches process templates from your org (Agile, Scrum, CMMI, custom)
Shows all work item types — check the ones you want the AI to use
Opens a field-access table per work item type:
- ai — AI can read and write this field
- readonly — AI can read but not modify
- none — field is completely hidden from the AI
Downloads .azdo-mcp.json to your workspace root

Commit .azdo-mcp.json with your repo. The gateway reads it on every call.

5 — Use your AI

Open Claude Code, Copilot Chat, or Cursor and start:

Show me the open bugs in the current sprint
Create a Feature under Epic 42 titled "Auth rework"
What's the status of PR [#77](https://github.com/Zer0skd/azure-devops-mcp/issues/77)?
Run pipeline "Deploy to staging" and watch it
Show me the wiki page on our branching strategy

Extension commands

Command	What it does
`AzDO MCP: Configure`	Opens the connection webview — set mode, token, project scope, then saves to VS Code + Claude
`AzDO MCP: Configure Process & Work Items`	Wizard: process template → WIT selection → field access → downloads `.azdo-mcp.json`
`AzDO MCP: Change Project Scope`	Quick-pick to limit which AzDO projects are accessible (syncs to gateway)
`AzDO MCP: Show Connection Status`	Panel: token info, tier, tool count, org URL
`AzDO MCP: Open Babylon's Factor Portal`	Opens the portal in your browser

The configure panel (v2.1.1+)

The configure flow is a full webview panel, not sequential dialogs.

┌─────────────────────────────────────────────────────────┐
│ AzDO MCP — Configure Connection                          │
│                                                          │
│  Mode:  ○ SaaS  ○ Self-Hosted                           │
│                                                          │
│  Bearer token: ●●●●●●●●●●●●●●●●  [Get token ↗]         │
│                                                          │
│  [Test Connection]  → ✓ Connected · Tier: admin         │
│                                                          │
│  Project scope:                                          │
│    ☑ FabLab                                             │
│    ☐ HomeLab                                            │
│                                                          │
│  [Save Configuration]                                    │
└─────────────────────────────────────────────────────────┘

When you click Save, the extension:

Writes azdoMcp.mode, azdoMcp.bearerToken, azdoMcp.serverUrl, azdoMcp.projectScope to VS Code global settings
Writes (or updates) the azure-devops server block in ~/.claude.json
Calls the gateway's /account/scope PATCH to sync project scope server-side
Refreshes the sidebar status tree

The AzDO MCP icon appears in the VS Code Activity Bar (left ribbon). Click it to see:

Connection status: Connected / Not configured / Error
Tier and org URL
Quick links: Configure, Process Setup, Change Scope, Open Portal

`.azdo-mcp.json` — process config format

The process wizard generates a file like this:

{
  "$schema": "https://babylons-factor.com/schemas/azdo-mcp-process.schema.json",
  "processId": "adcc42ab-9882-485e-a3ed-7678f01f66bc",
  "processName": "Agile",
  "hierarchy": ["Epic", "Feature", "User Story", "Task", "Bug"],
  "workItemTypes": {
    "Microsoft.VSTS.WorkItemTypes.Epic": {
      "name": "Epic",
      "fields": {
        "System.Title":       "ai",
        "System.Description": "ai",
        "System.State":       "ai",
        "System.AssignedTo":  "readonly",
        "System.Rev":         "none",
        "System.Watermark":   "none"
      }
    },
    "Microsoft.VSTS.WorkItemTypes.Feature": {
      "name": "Feature",
      "fields": { ... }
    }
  },
  "_generatedAt": "2026-06-18T14:00:00.000Z"
}

The gateway reads this file at request time to:

Filter which work item types appear in AI responses
Block writes to readonly fields
Completely omit none fields from any AI context

Commit .azdo-mcp.json to your repository root. All team members using the gateway with your project will automatically follow these rules.

DevSecOps team workflow

Who configures what

Role	What they do
Team lead / scrum master	Runs `AzDO MCP: Configure Process & Work Items` once, commits `.azdo-mcp.json`
Each developer	Runs `AzDO MCP: Configure` with their own token, optionally narrows project scope
Security / compliance	Reviews `.azdo-mcp.json` — which fields the AI can write — before approving

Setting field-level rules for your process

Typical patterns:

Field	Recommendation	Why
`System.AssignedTo`	`readonly`	Let humans assign, let AI inform
`System.Description`	`ai`	AI should write requirements from discussions
`System.Rev`, `System.Watermark`	`none`	Internal tracking — no AI value, just noise
`System.State`	`ai`	AI should transition items through sprint flow
`Microsoft.VSTS.Common.Priority`	`readonly`	Priority is a human decision
`System.AreaPath`	`readonly` or `none`	Team topology should stay human-controlled

Example: AI-assisted sprint flow

Dev: "What's in the current sprint and what's blocked?"
AI:  azdo_backlog_sprint() → lists all work items, shows blocked flag

Dev: "Mark task [#88](https://github.com/Zer0skd/azure-devops-mcp/issues/88) done and create a PR review task for @alice"
AI:  azdo_wi_update(88, {System.State: "Done"})
     azdo_wi_create(type=Task, parent=88's Story, assignedTo=alice, ...)

Dev: "Summarize the open PRs and flag ones waiting more than 24h"
AI:  azdo_repo_pr_list() → filters, computes age, formats summary

Dev: "Run the staging deploy pipeline"
AI:  azdo_pipelines_list() → confirms ID → azdo_pipeline_run(...)
     azdo_pipeline_get_run(...) → streams status

Branching + PR discipline with AI

The gateway's security rules prevent the AI from pushing directly to protected branches (main, master, production). The AI can:

Create feature branches: azdo_repo_branch_create(name="feat/42-auth-rework")
Create PRs with reviewer + work item links: azdo_repo_pr_create(..., work_item_ids=[42])
Vote on PRs, add review comments: azdo_repo_pr_vote(), azdo_repo_pr_thread_create()

Humans always merge. The AI does the heavy lifting of setup and review.

59 Available tools

Tools are grouped by tier. Each tier includes all tools from the tier below it.

All tiers

Session & Identity

Tool	Description
`azdo_token_info`	Your token tier, org URL, and available tool groups
`azdo_session_start`	Create or reuse a work session (User Story in AzDO)
`azdo_session_end`	Close a session with a summary
`azdo_context_get`	Current session defaults (project, team, scope)
`azdo_context_set`	Set defaults for the current session

Projects

Tool	Description
`azdo_projects_list`	All projects in the organisation
`azdo_project_get`	Project metadata, process template, capabilities

Work Items

Tool	Description
`azdo_wi_create`	Create any work item type with fields, parent link, area, iteration
`azdo_wi_get`	Full work item: all fields, relations, history
`azdo_wi_update`	Update one or more fields
`azdo_wi_comment`	Add a comment / history entry
`azdo_wi_query`	WIQL query — returns matching work items
`azdo_wi_hierarchy`	Item + full child tree (Epics → Features → Stories → Tasks)
`azdo_wi_link`	Link two work items (child, relates-to, duplicate, etc.)
`azdo_wi_batch_get`	Get up to 200 work items by ID in one call
`azdo_wi_search`	Full-text search across all work items

Boards & Backlogs

Tool	Description
`azdo_backlog_product`	Product backlog for a team
`azdo_backlog_sprint`	Sprint backlog — current or named sprint
`azdo_iteration_current`	Current active sprint for a team
`azdo_iterations_list`	All sprints / iterations
`azdo_teams_list`	All teams in a project
`azdo_members_list`	Members of a team
`azdo_areas_list`	Area path tree (5 levels deep)

Wiki

Tool	Description
`azdo_wiki_list`	Wikis in a project
`azdo_wiki_page_get`	Get a wiki page by path
`azdo_wiki_page_upsert`	Create or update a wiki page

Developer tier and above

Repositories

Tool	Description
`azdo_repos_list`	All Git repos
`azdo_repo_create`	Create a new repo
`azdo_repo_branches_list`	List branches
`azdo_repo_branch_create`	Create a branch from a ref
`azdo_repo_branch_delete`	Delete a branch
`azdo_repo_commits_list`	Commits with author / date / path filters
`azdo_repo_file_get`	Get file content at any ref
`azdo_repo_file_push`	Create or update a file
`azdo_repo_file_delete`	Delete a file
`azdo_repo_tags_list`	List annotated tags
`azdo_repo_tag_create`	Create an annotated tag

Pull Requests

Tool	Description
`azdo_repo_pr_list`	List PRs with status / reviewer filters
`azdo_repo_pr_create`	Create a PR with reviewers + work item links
`azdo_repo_pr_get`	Get a PR by ID
`azdo_repo_pr_update`	Update title, description, or status
`azdo_repo_pr_vote`	Approve / reject / wait on a PR
`azdo_repo_pr_threads_list`	All review threads
`azdo_repo_pr_thread_create`	Add a review comment
`azdo_repo_pr_thread_reply`	Reply to a thread

Code Search

Tool	Description
`azdo_code_search`	Full-text search across all repos

Admin tier

Pipelines & Builds

Tool	Description
`azdo_pipelines_list`	List YAML and classic pipelines
`azdo_pipeline_run`	Trigger a run with optional branch override + variables
`azdo_pipeline_get_run`	Get run status and result
`azdo_builds_list`	Build history with status / branch filters
`azdo_build_get`	Full build with timeline
`azdo_build_logs`	Task-level logs

Team & Area Management

Tool	Description
`azdo_iteration_create`	Create a sprint
`azdo_area_create`	Create an area path
`azdo_team_create`	Create a team
`azdo_team_area_set`	Assign area ownership to a team
`azdo_team_member_add`	Add a member to a team

Pricing

SaaS plans are per developer per month. Cancel anytime.

Plan	Price	Tool groups	Tools
Boards	€6 / dev / mo	Work items, backlogs, sprints, wiki, teams	39
Developer	€12 / dev / mo	Boards + repos, branches, PRs, code search	53
Admin	€18 / dev / mo	Developer + pipelines, builds, team management	59
Self-Hosted	€49 one-time	Source code + license key, run your own gateway forever	59

Subscribe at https://51-15-214-19.nip.io

PAT scopes by plan

When you register your PAT in the portal, the gateway uses it to call Azure DevOps REST on your behalf.

Boards — minimum scopes:

vso.work — read work items, queries, backlogs
vso.work_write — create and update work items
vso.project — read project metadata, teams
vso.graph (read) — list team members

Developer — all Boards scopes, plus:

vso.code — repos, branches, commits, files, PRs
vso.code_status — PR votes and status updates

Admin — all Developer scopes, plus:

vso.build — read pipelines
vso.build_execute — trigger pipeline runs
vso.graph_manage — create teams, manage membership

Start with Full access scoped to your org while testing. Narrow scopes once everything works.

Self-hosted deployment

For teams that need data sovereignty, air-gapped environments, or unlimited usage:

Buy a Self-Hosted license at the portal (€49 one-time)
Download the source package from the portal Releases tab (includes server_local.py, requirements.txt, setup guide)

Install and run:

pip install fastmcp azure-devops msrest uvicorn
uvicorn server_local:app --host 0.0.0.0 --port 9004

In VS Code, run AzDO MCP: Configure → toggle Self-Hosted → enter http://your-server:9004/mcp

The self-hosted gateway has no usage limits and stores no data outside your infrastructure. One purchase, run it indefinitely — no recurring fees.

Security model

No data stored: PAT and work item data are never persisted by the gateway. Every call is forwarded live to the Azure DevOps REST API and discarded.
Field-level access control: The .azdo-mcp.json config you generate determines exactly which fields the AI can read or modify. The gateway enforces these rules server-side on every call.
Per-developer tokens: Each user has their own token scoped to their own PAT. There are no shared org-level credentials.
Protected branches: The gateway blocks direct writes to main, master, production, prod, and release branches. All code changes must go through PRs.
Audit log: Every gateway call is logged in the audit_log table with tool name, token (short), and timestamp. Available to system administrators.

Requirements

VS Code 1.85 or later
An Azure DevOps organisation (cloud, or Server 2022+)
A bearer token from https://51-15-214-19.nip.io

Troubleshooting

"Configure Process" returns 404 Upgrade to v2.1.0 or later — gateway routing for /process/* was fixed in that release.

My token stopped working after reconfiguring Run AzDO MCP: Configure again, re-enter your token, and click Save. Confirm with AzDO MCP: Show Connection Status.

Self-hosted: connection refused or 404 Ensure your URL ends with /mcp (e.g. http://localhost:9004/mcp). The gateway serves MCP at /mcp and REST at /process/* and /account/* — both under the same host.

Claude Code doesn't see the MCP server after configuring The extension writes to ~/.claude.json. Reload VS Code, or run claude mcp list in a terminal to verify the azure-devops entry exists. If it doesn't, run AzDO MCP: Configure again.

Project scope changes aren't reflected in the AI Project scope is synced to the gateway server-side. Changes take effect immediately for new conversations. Existing active sessions may need to be restarted.

Changelog

v2.1.1

Configure panel now a webview — AzDO MCP: Configure opens a full webview panel instead of sequential QuickPick/InputBox dialogs. Includes inline Test Connection, project scope checkboxes, and a single Save button.
Fixed: configure panel now correctly pre-fills current settings (mode, token, projects)
Pipeline: fixed YAML parsing error that caused instant-cancel builds; version bump now commits correctly with [skip ci]

v2.1.0

59 tools — added azdo_context_get, azdo_context_set, azdo_repo_file_push, azdo_repo_file_delete, azdo_repo_branch_delete
Fixed 404 errors on AzDO MCP: Configure Process & Work Items (gateway routing)
Token persistence fix — previously configured tokens now retained after reconfiguration

v2.0.0

Project scope selector — limit which AzDO projects the AI can access via the sidebar or AzDO MCP: Change Project Scope
Version alignment with AzDO portal extension

v1.4.0

Sidebar panel — AzDO MCP icon in the activity bar; click to see connection status and launch setup
Single-token flow — process wizard no longer needs a separate PAT; your gateway token is all you need

v1.3.0

Added AzDO MCP: Configure Process & Work Items — field-level access wizard, .azdo-mcp.json download

v1.2.0

Added auto-write to ~/.claude.json on save — Claude Code auto-discovers the server

v1.1.0

Self-hosted mode — configure your own gateway URL + optional token

v1.0.0

Initial release: SaaS connection configuration, MCP server registration

Support

Questions, billing, and account: https://51-15-214-19.nip.io/support

AzDO MCP — Azure DevOps via AI

babylons-factor