AzDO MCP — Azure DevOps for AI Assistants

by Babylon's Factor

Give Claude Code, Cursor, and any MCP-compatible AI assistant direct, structured access to Azure DevOps — boards, repos, pipelines, and wikis — through the Model Context Protocol.

What this extension does

This extension connects VS Code and its AI clients (Claude Code, Copilot, Cursor) to the AzDO MCP Gateway in two steps:

Auto-configures the MCP connection — writes your gateway URL and bearer token directly into ~/.claude.json and VS Code MCP settings. No manual JSON editing.
Guides the process setup — walks you through selecting your process template, work item types, and per-field AI access permissions, then downloads a .azdo-mcp.json config the gateway uses to enforce those rules.

Quick Start

1. Get a subscription

Sign up at https://portal.babylons-factor.com and copy your bearer token. (Or deploy a self-hosted gateway — see the Self-Hosted section below.)

2. Install this extension

Search "AzDO MCP" in the VS Code Extensions panel, or install from the marketplace page.

3. Open the Command Palette and run `AzDO MCP: Configure`

The extension will:

For SaaS mode: ask only for your bearer token (gateway URL is pre-configured)
For self-hosted mode: ask for your gateway URL and bearer token
Test the connection live
Write the MCP server config to ~/.claude.json and VS Code MCP settings automatically
Show: "AzDO MCP configured — Claude Code and VS Code MCP clients are now connected."

4. Run `AzDO MCP: Configure Process & Work Items`

Walk through the wizard:

Step 1 — Select your process template (Agile, Scrum, CMMI, or custom) — fetched from the gateway using your stored token
Step 2 — Choose which work item types the AI should see (Epic, Feature, Story, Task, Bug…)
Step 3 — Set per-field access in a table editor: ai (read/write), readonly, or none (hidden from AI)
Download — saves .azdo-mcp.json to your workspace root. Commit this file with your repo.

5. Use your AI assistant

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

Show me the open bugs in the current sprint
Create a Feature under Epic 142 for the new auth flow
What's the status of PR [#77](https://github.com/Zer0skd/azure-devops-mcp/issues/77)?
Run pipeline "Deploy to staging"

Commands

Command	Description
`AzDO MCP: Configure`	Set connection mode + token, auto-writes MCP config
`AzDO MCP: Configure Process & Work Items`	Process wizard → downloads `.azdo-mcp.json`
`AzDO MCP: Show Status`	Connection health, token info, tool count
`AzDO MCP: Open Portal`	Opens the subscription portal

54 Tools — Full Reference

Tools are grouped by category. The Tier column shows the minimum subscription required.

Session & Identity

Tool	Description	Tier
`azdo_token_info`	Token info: org URL, tier, available tool groups	All
`azdo_session_start`	Start a stateful session (batches credentials across calls)	All
`azdo_session_end`	Close an active session	All

Projects

Tool	Description	Tier
`azdo_projects_list`	List all projects in the organisation	All
`azdo_project_get`	Project details, process template, capabilities	All

Work Items

Tool	Description	Tier
`azdo_wi_create`	Create any work item type with fields + parent link	All
`azdo_wi_get`	Get a work item by ID with all fields	All
`azdo_wi_update`	Update fields on an existing work item	All
`azdo_wi_comment`	Add a comment to a work item	All
`azdo_wi_query`	Run a WIQL query, return matching work items	All
`azdo_wi_hierarchy`	Get a work item and its full child tree	All
`azdo_wi_link`	Create a link between two work items	All
`azdo_wi_batch_get`	Get multiple work items by ID in one call	All
`azdo_wi_search`	Full-text search across work items	All

Boards & Backlogs

Tool	Description	Tier
`azdo_backlog_product`	Get the product backlog for a team	All
`azdo_backlog_sprint`	Get the sprint backlog (current or named sprint)	All
`azdo_iteration_current`	Current active iteration for a team	All
`azdo_iterations_list`	List all iterations / sprints for a team	All
`azdo_iteration_create`	Create a new sprint	Admin

Teams & Areas

Tool	Description	Tier
`azdo_teams_list`	List all teams in a project	All
`azdo_members_list`	List members of a team	Boards+
`azdo_areas_list`	List area paths in a project	Boards+
`azdo_area_create`	Create a new area path	Admin
`azdo_team_create`	Create a new team	Admin
`azdo_team_area_set`	Assign area path to a team	Admin
`azdo_team_member_add`	Add a member to a team	Admin

Wiki

Tool	Description	Tier
`azdo_wiki_list`	List all wikis in a project	All
`azdo_wiki_page_get`	Get a wiki page by path	All
`azdo_wiki_page_upsert`	Create or update a wiki page	All

Repositories

Tool	Description	Tier
`azdo_repos_list`	List all repositories in a project	Developer+
`azdo_repo_create`	Create a new repository	Developer+
`azdo_repo_branches_list`	List branches in a repository	Developer+
`azdo_repo_branch_create`	Create a branch from a commit or ref	Developer+
`azdo_repo_commits_list`	List commits with filtering by author, date, path	Developer+
`azdo_repo_file_get`	Get the content of a file at a given ref	Developer+
`azdo_repo_tags_list`	List tags in a repository	Developer+
`azdo_repo_tag_create`	Create an annotated tag	Developer+

Pull Requests

Tool	Description	Tier
`azdo_repo_pr_list`	List pull requests with status / reviewer filters	Developer+
`azdo_repo_pr_create`	Create a PR with reviewers and work item links	Developer+
`azdo_repo_pr_get`	Get a pull request by ID	Developer+
`azdo_repo_pr_update`	Update PR title, description, or status	Developer+
`azdo_repo_pr_vote`	Approve, reject, or wait on a pull request	Developer+
`azdo_repo_pr_threads_list`	List review threads on a pull request	Developer+
`azdo_repo_pr_thread_create`	Create a review comment thread	Developer+
`azdo_repo_pr_thread_reply`	Reply to an existing review thread	Developer+

Code Search

Tool	Description	Tier
`azdo_code_search`	Full-text search across all repos in the project	Developer+

Pipelines & Builds

Tool	Description	Tier
`azdo_pipelines_list`	List all YAML and classic pipelines	Admin
`azdo_pipeline_run`	Trigger a pipeline run with optional variables	Admin
`azdo_pipeline_get_run`	Get the status and result of a pipeline run	Admin
`azdo_builds_list`	List build history with status filters	Admin
`azdo_build_get`	Get full details of a specific build	Admin
`azdo_build_logs`	Get build task logs	Admin

Pricing

All plans are per-developer per month. Cancel anytime.

Plan	Price	Tools available
Boards	€6 / dev / mo	Work items, backlogs, sprints, wiki, session — 37 tools
Developer	€12 / dev / mo	Boards + repos, branches, PRs, code search — 50 tools
Admin	€18 / dev / mo	Developer + pipelines, builds, team/area management — 54 tools
Self-Hosted	€5 one-time	License key for your own gateway instance

Subscribe and manage your token at https://portal.babylons-factor.com

Self-Hosted Deployment

For teams that need full data sovereignty or air-gapped environments:

Purchase a Self-Hosted license at the portal (€5 one-time)
Download the server_local.py release package from the portal's Releases page
Install and run:

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

Configure this extension with http://your-server:9004/mcp as the gateway URL

Self-hosted gateways have no usage limits and store no data outside your environment. The license key is validated once at startup.

Security

No data stored: Your PAT and work item data are never persisted by the gateway. Every call is forwarded live to the Azure DevOps REST API.
Field-level access control: The .azdo-mcp.json config you generate enforces which fields the AI can read or write per work item type.
Per-developer tokens: Each user's token is scoped to their own PAT. No shared org credentials.

Minimum PAT scopes by plan

Boards (vso.work + vso.work_write + vso.project + vso.graph read)

Developer — Boards scopes plus:

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

Admin — Developer scopes plus:

vso.build + vso.build_execute — list and trigger pipelines
vso.graph_manage — create teams, manage membership

Tip: Start with Full access scoped to your org, then narrow scopes after verifying everything works.

Requirements

VS Code 1.85+
An Azure DevOps organisation (cloud or Server 2022+)
A bearer token from portal.babylons-factor.com (SaaS) or self-hosted license

What's new in v2.1.0

Fixed 404 errors on "Configure Process & Work Items" — gateway routing for /process/* and /account/* was fixed
Token persistence fix — previously configured tokens are now retained correctly after reconfiguration
Docs updated to accurately reflect SaaS vs self-hosted configure flow

What's new in v2.0.0

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

What's new in v1.4.0

Sidebar panel — AzDO MCP now appears in the VS Code activity bar (left ribbon). Click the icon to see connection status and launch setup from one place.
Single-token flow — The process wizard no longer asks for a separate PAT or org URL. Your gateway token is all you need — the gateway proxies AzDO API calls using your stored credentials.
Connection test now validates your token against the gateway on every configure (401 = clear error message).

Troubleshooting

"Configure Process" returns 404 errors

This was a gateway routing issue fixed in v2.1.0. Update the extension to the latest version — no other changes needed. The gateway now correctly routes /process/* and /account/* requests.

My old token stopped working after reconfiguring

If you reconfigured the connection with a new token, the extension stores the new one in VS Code global settings. Run AzDO MCP: Configure again to ensure the token is current, then run AzDO MCP: Show Status to verify the connection.

Self-hosted: commands return 404 or connection refused

Verify your self-hosted gateway URL ends with /mcp (e.g. http://localhost:9004/mcp). The gateway serves the MCP endpoint at /mcp and REST API at /process/* and /account/* — all under the same host.

Support

Portal, billing, and account: https://portal.babylons-factor.com/support

AzDO MCP — Azure DevOps via AI

babylons-factor