devops-mcp

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.

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.

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

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

Pipelines (10 tools)

Repositories (7 tools)

Pull Requests (17 tools)

Work Items (10 tools)

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) and work item write operations 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.