Wire it into an AI agent

Everything the CLI does is also available to an agent — as MCP tools, as ready-made skills and subagents, or as plain Python callables. This page covers getting an agent (Claude Code, primarily) talking to your Azure DevOps organization.

One command to set it all up

devops-utils setup all

That installs the bundled skills, the Claude Code subagents, and an Azure DevOps env scaffold, defaulting to user scope (~/.claude). Nothing needs to be installed first:

uvx --from "devops-utils[all]" devops-utils setup all

Registering the MCP server is opt-in — the skills drive the devops-utils azdo CLI through uvx, so many setups need no server entry at all:

devops-utils setup all --with-mcp     # ... and register the MCP server
devops-utils setup all --project      # scope to this repo (./.claude, ./.mcp.json)

Individual steps, or an arbitrary directory:

devops-utils setup skills --dest ./agent-skills
devops-utils setup agents            # ~/.claude/agents/*.md
devops-utils setup mcp --dest .
devops-utils setup env
devops-utils setup tracker --project-name MyProject --done-state Closed

Nothing is clobbered silently

When a target already exists, setup asks about it one item at a time:

$ devops-utils setup all
wrote  ~/.claude/skills/azure-devops-research/SKILL.md
overwrite ~/.claude/agents/azdo-build-analyst.md? [y]es / [n]o / [a]ll / [q]uit / [d]iff: n
skip   ~/.claude/agents/azdo-build-analyst.md (kept existing)

y overwrites, n keeps, a overwrites all remaining, q stops asking and keeps the rest, d shows a diff of the bundled version against yours first. Files identical to the bundled copy are reported as same and never prompt. An a/q answer carries across the remaining steps of setup all.

--force (or -y/--yes) answers yes to everything. Unattended runs — no terminal, or DEVOPS_UTILS_SKIP_CONFIRMATION set — keep every existing file and exit 0, so CI never blocks on a prompt or refreshes by surprise; pass --force there if a refresh is what you want.

What gets installed

Skills

Skill	For
`azure-devops`	Create, comment, tag, link and attach to work items
`azure-devops-research`	Read-only status research: pending items, build failures, repo search
`find-workitems`	Query recipes — by type, tag, `--parent`, area path
`setup-issue-tracker`	Guided, validated setup of a repo’s tracker config
`git-history-workitems`	Mine git history into a Feature/Story backlog, ready for `azdo apply`
`sanitize`	Mask secrets in a Kubernetes manifest

Subagents

setup agents installs three read-only Azure DevOps research subagents for Claude Code:

azdo-workitem-analyst — pending items, assigned-to-me via the WIQL @Me macro, type/tag/state filters, following relations.
azdo-build-analyst — definitions, run status by branch/result, failure diagnosis via timeline plus log tailing.
azdo-repo-analyst — repo, file-path and code search.

They read; they never write. Writes stay with the main assistant, gated by the MCP server’s human confirmation.

Registering the MCP server

setup mcp writes the zero-install uvx launcher — only uv has to be present:

{
  "mcpServers": {
    "devops-utils": {
      "command": "uvx",
      "args": ["--from", "devops-utils[mcp]", "devops-utils-mcp"],
      "env": {}
    }
  }
}

Pass --no-uvx to register the bare devops-utils-mcp console script instead (requires pip install "devops-utils[mcp]" so it’s on PATH). Existing mcpServers entries for other servers are merged, not replaced, and an existing devops-utils entry prompts first.

The server reads the same environment variables as the CLI (Install and configure) — the process that launches your agent must have them exported, or put them in the entry’s env block.

Writes ask a human first

The MCP write tools (azdo_create_work_item, azdo_update_work_item, azdo_comment_work_item, azdo_set_work_item_tags, azdo_add_work_item_link, azdo_remove_work_item_link, azdo_add_work_item_attachment, azdo_tag_build, azdo_comment_pull_request, azdo_apply_plan) describe the pending change and apply it only when you accept the MCP elicitation. Declining writes nothing and returns a cancelled status.

If the client can’t prompt — elicitation unsupported, or a non-interactive run — the write is blocked rather than silently applied, unless DEVOPS_UTILS_SKIP_CONFIRMATION is truthy. Read tools are never gated.

Use it as a Claude Code plugin

The same skills and subagents ship as a Claude Code plugin named devops-utils, which namespaces them (devops-utils:azure-devops-research, devops-utils:azdo-workitem-analyst, …) instead of installing bare names:

/plugin marketplace add carneirofc/devops-utils
/plugin install devops-utils@carneirofc
/reload-plugins

(carneirofc/devops-utils is GitHub shorthand; a local checkout path works too.)

The plugin ships only skills and agents. The subagents call the MCP tools (mcp__devops-utils__azdo_*), so using them still needs devops-utils setup mcp. The skills themselves work without it, driving the CLI through uvx. MCP is deliberately not bundled: a plugin-scoped server would rename those tools and break the agents that call them.

Point issue-tracker skills at Azure DevOps

Skills in the style of mattpocock/skills (triage, wayfinder, to-tickets, …) read a repo-local config file, docs/agents/issue-tracker.md, to learn how to talk to the issue tracker — GitHub’s gh CLI by default. To point them at Azure DevOps work items instead, run in the target repo:

devops-utils setup tracker --project-name MyProject --done-state Closed \
  --org-url https://dev.azure.com/myorg \
  --parent-epic 1400 --area-path 'MyProject\MyTeam' --default-tag my-repo

This writes docs/agents/issue-tracker.md and docs/agents/triage-labels.md, mapping every tracker operation — create, comment, labels→tags, close, claim, blocking links, PR references — onto devops-utils azdo and the azdo_* MCP tools.

--done-state is whatever “closed” is called in your process template (Closed, Done, Resolved, …).
The optional org URL, parent Epic, area path and repeatable default tags land in a Defaults for this repo table that agents apply on every create and query. New items land under the right Epic with the right area and tags, and “what’s pending?” searches surface this repo’s items first.

For a guided flow that asks for each value and validates it against the live organization, use the bundled setup-issue-tracker skill. The find-workitems skill holds the matching query recipes.

Without an agent framework

The tools are plain Python functions — no MCP, no framework:

from devops_utils.agent import tools

builds = tools.azdo_list_builds("MyProject", branch="main", results=["failed"], top=5)
timeline = tools.azdo_get_build_timeline("MyProject", builds[0]["id"])

Their docstrings are written to be read by an LLM, so they register cleanly with whatever tool-calling layer you already use. Full signatures are in the API reference.