devops-mcp 1.6.0

An MCP server that exposes Azure DevOps as tools for LLMs — pipelines, repositories, pull requests, and work items. Built with MCPServer (the Python MCP SDK's ergonomic server class) over stdio transport.

Communicates over stdio and works with GitHub Copilot, Claude Code, and any MCP-compatible client.

Quick Start

1. Install dependencies

uv sync

2. Configure — add to your MCP client config (see MCP Client Setup below).

3. Run the server

uv run devops-mcp

Installation

Prerequisites

• Python >=3.10
• uv (recommended)
• A Microsoft Entra ID identity with access to Azure DevOps

Requires the MCP Python SDK >=2.0.0. Versions up to and including 1.3.0 require SDK 1.x and will not start against 2.x — the SDK removed mcp.server.fastmcp in 2.0.0, so an older release installed today fails at import with ModuleNotFoundError: No module named 'mcp.server.fastmcp'. Upgrade to 1.4.0 or later.

Install dependencies

uv sync

Build the package

uv run python -m build

Configuration

All configuration is driven by environment variables — no secrets in code, no hardcoded org names or tenant IDs.

Authentication

The server uses Microsoft Entra ID (Azure AD) OAuth 2.0 via the azure-identity library. Set AZDO_AUTH_TYPE to select a method.

For default / local dev: run az login once — DefaultAzureCredential will pick it up automatically.

For interactive: a browser window opens on first use. Set AZDO_TENANT_ID to constrain sign-in to a specific Entra ID tenant (recommended when multiple accounts are in use). The persistent token cache is on by default, so subsequent restarts are silent; set AZDO_EPHEMERAL_TOKEN=true to opt out.

For client_secret: also set AZDO_TENANT_ID, AZDO_CLIENT_ID, and AZDO_CLIENT_SECRET.

Security

Safe-by-default write and delete gates

Write and delete tools are not registered by default — they do not appear to the agent at all until explicitly enabled. The server is read-only until AZDO_ALLOW_WRITE=true and/or AZDO_ALLOW_DELETE=true are set. Each flag is independent; set only the ones you need.

Two tools sit behind the delete gate, and they are the only ones annotated destructiveHint: true.

devops_delete_query is the milder of the two: query deletion is soft with no permanent option, so a deleted query or folder can be restored with devops_update_query(undelete=true) — except its permissions, which do not come back. Deleting a folder cascades to everything inside it.

devops_delete_work_item's default is the recoverable operation: the work item goes to the project's recycle bin and a human can restore it from Boards > Work Items > Recycle Bin. The unrecoverable operation is opt-in per call via destroy=true, which erases the work item and all its revisions with no undo — Azure DevOps guards that separately with the project-level Permanently delete work items permission, held by Project Administrators by default, so an ordinary contributor's token gets an HTTP 403 rather than a silent permanent delete.

Env-driven configuration

All configuration is supplied via environment variables. No secrets, org names, project names, or tenant IDs are hardcoded. .vscode/mcp.json is gitignored because it may contain credentials.

Attachment URLs are rebuilt, never followed

devops_get_work_item_attachment accepts a url so an agent can paste the <img src> it found in a work item description. That description is user-authored content and therefore a prompt-injection surface: fetching an arbitrary URL with an Authorization: Bearer … header attached would hand a live Azure DevOps token to whatever host an injected description names.

The guard is not a host allowlist — an open redirect on a Microsoft-owned host would defeat that. The URL is parsed and then discarded: the scheme must be https, the netloc must carry no userinfo and no non-443 port, the parsed hostname must be dev.azure.com or {org}.visualstudio.com, the path must be the /_apis/wit/attachments/{guid} route, and the organization named in the URL must match the resolved one. Only the attachment GUID and fileName survive; the request is rebuilt against the resolved organization. Every rejection happens before a token is acquired, so a crafted URL never causes one to be minted.

Two relative shapes are accepted alongside the absolute one, because the web UI can write either into an <img src>: protocol-relative //dev.azure.com/{org}/…, which gets the identical host, userinfo and port treatment with the scheme taken to be https, and site-relative /{org}/_apis/wit/attachments/{guid}, which has no host to check but still has to name the resolved organization in its first path segment. Neither weakens anything — the URL is discarded and the request rebuilt either way, so there is no host to follow — and a relative URL naming a different organization is refused and counted exactly like an absolute one. The alternative was worse: before, they matched nothing at all and were silently missed, so a caller saw a clean result rather than a rejection.

The same guard runs on every URL the other attachment tools handle, for two more reasons:

• devops_list_work_item_attachments scrapes URLs out of field and comment text — the most attacker-influenceable input in the product. A URL that fails validation is dropped and only counted (rejected_urls); it is never repeated back, because echoing it would relay to the model exactly the payload the guard just caught. Only canonical rebuilt URLs are ever surfaced.
• devops_link_work_item_attachment stores a URL on the work item. An unvalidated one there is a persistent injection vector re-read by every future reader, not a single bad request — so the supplied URL is parsed, discarded, and the relation is rebuilt from the resolved organization before anything is written.

Attachment uploads are image-only, by bytes as well as by name

devops_upload_work_item_attachment reads a local file chosen by a model, which in the general case is a data-exfiltration primitive. Four guards apply: it is registered only under AZDO_ALLOW_WRITE; the file name must end in .png, .jpg, .jpeg, .gif or .webp; the actual bytes must carry a matching image signature, so renaming id_rsa to x.png is refused; and the path is resolved (collapsing ..) and must be a regular file. Set AZDO_ATTACHMENT_ROOT to additionally confine reads to one directory tree. Weakening the extension allowlist or the magic-byte check — for example "to support PDFs" — is a security change, not a feature tweak.

Stdout reserved for MCP transport

Stdout is exclusively reserved for MCP stdio transport messages. All server logs (including auth events) go to stderr via the Python logging module. Never redirect stdout to a log file.

Token cache caveats (interactive auth)

By default the MSAL token cache is encrypted at rest using the OS secret store (Windows DPAPI, macOS Keychain, Linux libsecret). The AuthenticationRecord sidecar stored at ~/.devops-mcp/auth-record.json contains only account metadata (home account ID, tenant, authority, username) — no tokens or client secrets.

On headless Linux without a secret store (e.g., no GNOME Keyring / libsecret installed), the OS-encrypted cache may be unavailable. The server logs an actionable warning and falls back to an in-memory-only cache. Set AZDO_EPHEMERAL_TOKEN=true to suppress the warning and always use in-memory cache on such hosts.

Multiple tenants/accounts on one host (interactive auth)

The default cache and sidecar filenames (devops-mcp.cache, ~/.devops-mcp/auth-record.json) are shared per host, so two interactive sessions signed in to different tenants/accounts would overwrite each other's pinned account. Give each session a distinct AZDO_TOKEN_CACHE_PROFILE (e.g. prod, dev) to keep their caches and AuthenticationRecord sidecars separate. The profile is a tenant-wide cache key: each entry signs in once (its own browser prompt) and then restarts silently as its own account, while tools still receive the specific organization/project per call. The profiles never collide.

Register two server entries, each with its own profile and (recommended) matching AZDO_TENANT_ID:

{
  "servers": {
    "devops-mcp-prod": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "devops-mcp"],
      "env": {
        "AZDO_AUTH_TYPE": "interactive",
        "AZDO_TENANT_ID": "<prod-tenant-id>",
        "AZDO_TOKEN_CACHE_PROFILE": "prod"
      }
    },
    "devops-mcp-dev": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "devops-mcp"],
      "env": {
        "AZDO_AUTH_TYPE": "interactive",
        "AZDO_TENANT_ID": "<dev-tenant-id>",
        "AZDO_TOKEN_CACHE_PROFILE": "dev"
      }
    }
  }
}

Resilience behavior

These behaviors are built in and require no configuration:

• Automatic retries — requests that receive 429 (throttling) or transient gateway errors (502, 503, 504) are retried automatically with back-off and Retry-After header honoring. Non-idempotent writes (POST, PATCH) are not retried on 5xx — a gateway error on a write may arrive after the server has already committed the operation; only 429 (which guarantees the request was rejected before processing) is safe to retry on all methods.
• Response size cap — responses larger than 5 MB are replaced with an error asking the agent to narrow the query. For large pipeline logs, prefer devops_get_run_timeline to triage without pulling log text at all; devops_get_run_log_content defaults to a bounded 500-line page (max_lines, tail, start_line/end_line) with a paging envelope, and devops_search_run_log returns only matching lines.
• Auth timeout — credential acquisition is bounded by AZDO_AUTH_TIMEOUT_SECONDS (default 30 s). A slow or hung auth call releases the per-scope lock so subsequent callers are not serialized indefinitely.

MCP Client Setup

GitHub Copilot (VS Code)

Add to .vscode/mcp.json in your project root. Note: .vscode/mcp.json is gitignored because it may contain secrets.

Default / local dev (recommended):

{
  "servers": {
    "devops-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "devops-mcp"],
      "env": {
        "AZDO_ORGANIZATION": "<your-org>",
        "AZDO_PROJECT": "<your-project>"
      }
    }
  }
}

With write tools enabled:

{
  "servers": {
    "devops-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "devops-mcp"],
      "env": {
        "AZDO_ORGANIZATION": "<your-org>",
        "AZDO_PROJECT": "<your-project>",
        "AZDO_ALLOW_WRITE": "true"
      }
    }
  }
}

Service principal (CI/CD):

{
  "servers": {
    "devops-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "devops-mcp"],
      "env": {
        "AZDO_AUTH_TYPE": "client_secret",
        "AZDO_TENANT_ID": "<your-tenant-id>",
        "AZDO_CLIENT_ID": "<your-client-id>",
        "AZDO_CLIENT_SECRET": "<your-client-secret>",
        "AZDO_ORGANIZATION": "<your-org>",
        "AZDO_PROJECT": "<your-project>"
      }
    }
  }
}

Tools

66 tools across 9 domains. Tools marked with a gate are only registered when the corresponding env flag is set.

Pipelines (10 tools)

Repositories (8 tools)

Pull Requests (17 tools)

Work Items (15 tools)

Saved Queries (7 tools)

Queries and folders are addressed either by GUID or by path — Shared Queries/Website team/All Bugs. The only two roots are Shared Queries (project-wide) and My Queries (yours alone); neither root can be renamed or moved through these tools, because Azure DevOps permits the rename and it breaks path addressing for everything beneath it.

A soft-deleted item is addressable only by GUID: include_deleted=true on its path still returns 404. To recover one, read its parent folder with devops_get_query(depth=1, include_deleted=true), take the child's GUID from the listing, then devops_update_query(query=<guid>, undelete=true).

Discovery (2 tools)

Advanced Security (3 tools)

Requires GitHub Advanced Security for Azure DevOps (GHAzDo) to be enabled on the repository.

Service Connections (2 tools)

Read-only. Credential values are never returned — authorization.parameters is projected onto an explicit allowlist of non-secret identity fields (never a denylist, since parameter names are type-specific and open-ended), and the withheld field names (never values) are reported back so an agent can tell a credential exists without seeing it.

Both tools report health as three separate signals: is_ready (provisioning finished), is_disabled (turned off) and is_outdated (stored config no longer matches the underlying resource — typically an expired or rotated secret). A connection can be ready and still fail to authenticate, so is_ready alone is not a health check.

Variable Groups (2 tools)

Read-only. Secret variables (isSecret: true) never have their value returned, regardless of what the server sends back. Non-secret variables whose name matches a credential-like pattern (e.g. DB_PASSWORD) are withheld too and flagged redacted: "name_heuristic" — a safety net for values the author forgot to mark secret.

API Reference

All tools use the Azure DevOps REST API. Pipeline, repository, and discovery tools use v7.1. Work item schema tools (devops_list_work_item_types, devops_list_work_item_fields) use v7.1. Service connection and variable group tools use v7.1 (GA — no preview moniker needed). PR tools (get/list/create/update/tag/link), work item write operations, and saved-query tools use v7.2-preview. Advanced Security alert tools use v7.2-preview.1 on the advsec.dev.azure.com host.

Note: run_id and build_id share the same numeric value — a Pipelines API run_id is identical to the Build API buildId for the same run. This enables cross-API calls (e.g., use devops_list_run_logs to get log IDs, then devops_get_run_log_content with the same build_id).

Efficient log retrieval

Pipeline logs can be huge and expensive to read. Work from cheapest to most expensive:

1. devops_get_run_timeline — start here for "why did it fail." Returns a compact, failure-filtered timeline with inline error messages, often answering the question with zero log fetches.
2. devops_search_run_log — grep a specific log in-process; only matching lines (plus context) are returned, so non-matching content never reaches the model.
3. devops_get_run_log_content — read log text directly. Bounded to max_lines (default 500) with start_line/end_line/tail windowing and a paging envelope (has_more, next_start_line) to page through large logs or grab just the tail.