Azure DevOps MCP Server Workshop

Duration: 90 minutes Format: Presentation + Live Demo + Hands-on Lab Audience: Developers, platform & DevOps engineers, Azure DevOps administrators Focus: Installing and using the Azure DevOps MCP Server with AI agents — and how it compares to the REST API Lab Guide: ado-mcp-LAB.md (5 hands-on exercises against a sandbox project)

Workshop Overview

The Azure DevOps MCP Server brings Azure DevOps context — work items, repositories, pull requests, pipelines, wikis, and test plans — directly to AI agents such as GitHub Copilot. Instead of writing REST calls and parsing JSON, your team can ask in natural language: "List the bugs assigned to me in the current iteration" or "Summarise the failing tests in the last build of the Payments pipeline."

This workshop takes attendees from zero to productive: what the Model Context Protocol (MCP) is, how to install both the Remote (preview, hosted) and Local (npx/stdio) servers, how authentication and access scoping work, a guided tour of the tool surface, hands-on exercises against a sandbox project, and a thorough, decision-oriented comparison of the MCP server vs. the Azure DevOps REST API.

Note: The Azure DevOps MCP Server is a thin abstraction layer over the REST APIs. It does not replace the REST API — it makes Azure DevOps data and actions conversational and agent-accessible. Understanding when to reach for each is the central skill this workshop builds.

Learning Objectives

• Explain what MCP is and why an Azure DevOps MCP server matters for agentic workflows
• Install and configure the Remote MCP Server (public preview) and the Local MCP Server
• Understand the authentication models: Microsoft Entra ID (OAuth) vs. Personal Access Tokens
• Navigate the tool surface across all nine domains and run effective natural-language prompts
• Scope the server safely with read-only mode, toolsets, and individual-tool filtering
• Compare the MCP server and the REST API across capability, effort, determinism, security, and cost
• Decide which interface — MCP, REST, or both — fits a given scenario

Prerequisites

Session Agenda

Total: 90 minutes (format: concept → demo → discussion)

1. What Is MCP & Why Azure DevOps MCP (10 min)

Key Points

• Model Context Protocol (MCP) is an open standard that lets AI agents discover and call external tools through a consistent interface. Think of it as "USB-C for AI tools" — one protocol, many capabilities.
• An MCP server exposes a set of tools (each a focused operation with typed inputs/outputs). The MCP client (VS Code + Copilot, Visual Studio, Cursor, Claude, etc.) lets the model call those tools during a conversation.
• The Azure DevOps MCP Server exposes Azure DevOps operations as tools so an agent can read and act on your projects in natural language — no SDK, no hand-written REST calls, no JSON parsing.
• Microsoft's design principle: tools are concise, focused, and single-purpose — a thin abstraction over the REST APIs — leaving the complex reasoning to the language model.

Why It Matters

The Big Picture

graph LR
    Dev["User/Developer"] -->|natural language| Agent[AI Agent<br/>Copilot in VS Code]
    Agent -->|MCP tool calls| Server[Azure DevOps<br/>MCP Server]
    Server -->|REST under the hood| ADO[(Azure DevOps<br/>Services)]
    ADO -->|JSON| Server
    Server -->|structured results| Agent
    Agent -->|answer and actions| Dev

💡 Mental model: The MCP server is the translator and concierge between your agent and Azure DevOps. You speak intent; it speaks REST.

Discussion Points

• Where does your team currently lose time switching between the IDE and the Azure DevOps portal?
• Which routine Azure DevOps questions get asked over and over that an agent could answer instantly?
• What would it change if your agent could see work items, PRs, and build logs without copy/paste?

2. Setup, Installation & Authentication (15 min)

Key Points

There are two ways to run the server. Lead with the Remote server — it is the recommended path and requires no local installation. Use the Local server when you need a stdio setup, a non-Entra organisation, PAT auth, or a client that the remote preview does not yet support.

Remote Server — Quick Start (Recommended)

Create .vscode/mcp.json in your project:

{
  "servers": {
    "ado-remote-mcp": {
      "url": "https://mcp.dev.azure.com/{organization}",
      "type": "http"
    }
  },
  "inputs": []
}

Replace {organization} with your org name (e.g. contoso). Save the file, start the server from the MCP view in VS Code, authenticate with your Microsoft Entra account when prompted, and try: List ADO projects.

Note: You can omit the organisation from the URL (https://mcp.dev.azure.com/), but then you must provide the org name as context in each prompt.

Local Server — Installation (Alternative)

Add .vscode/mcp.json with an input prompt for the org name:

{
  "inputs": [
    {
      "id": "ado_org",
      "type": "promptString",
      "description": "Azure DevOps organization name (e.g. 'contoso')"
    }
  ],
  "servers": {
    "ado": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "${input:ado_org}"]
    }
  }
}

Save, click Start, switch Copilot Chat to Agent Mode, choose Select Tools, and run List ADO projects. The first tool call opens a browser to sign in.

Note: Use the @azure-devops/mcp@next nightly tag to preview the latest tools and fixes.

Authentication & Access Model

• Remote uses Microsoft Entra ID (OAuth) — your AI assistant authenticates as you, and every tool call respects your existing Azure DevOps permissions. No token to manage.
• Local supports Entra ID (including --authentication azcli to reuse your az login session) or a Personal Access Token (PAT) for scenarios where interactive sign-in is not possible.
• The server never grants more access than the signed-in identity already has. Permissions are enforced by Azure DevOps, not by the server.

Important: Today, only VS Code and Visual Studio support the Remote server, because other clients (Copilot CLI, Claude, Codex, Cursor) require dynamic OAuth client registration in Entra. For those clients, use the Local server.

🖥️ Demo: First Connection in Under Two Minutes

1. Open an empty folder in VS Code and create .vscode/mcp.json for the Remote server
2. Start the server from the MCP view; complete the Entra sign-in
3. Open Copilot Chat in Agent Mode and run List the projects in my Azure DevOps organization
4. Show the tool-approval prompt and the returned project list
5. (Optional) Swap to the Local config and show the org-name input prompt

Discussion Points

• Is your organisation connected to Entra ID? Which server should your teams start with?
• Where would PAT-based local auth be necessary (build agents, non-VS Code tools)?
• Should the server config (.vscode/mcp.json) be committed to your repos as a team default?

3. Capability Tour — Tools by Domain (15 min)

Key Points

The server organises its tools into nine domains. With the Local server you load only the domains you need (-d core work-items repositories); with the Remote server you scope with the X-MCP-Toolsets header. Always keep core enabled so the agent can resolve projects and teams.

Read vs. Write Tools

Each domain mixes read tools (list, get, search) and write tools (create, update, link, run). Write tools always surface a confirmation prompt in the client before they execute — the agent cannot silently mutate your project.

💡 Toolset hygiene: Loading every tool can overwhelm the model and hit client tool limits. Scope to the domains a given repo actually needs. A docs repo might load only core, wiki, and search.

High-Value Workflows the Tools Unlock

• Sprint triage: "Summarise my work items in the current iteration grouped by state."
• PR review prep: "Show the diff and linked work items for PR 142, and list unresolved comment threads."
• Build debugging: "Get the log for the failing stage of the last build and explain the root cause."
• Release notes: "List the work items completed in iteration Sprint-24 and draft release notes."
• Knowledge capture: "Create a wiki page documenting how we run the nightly pipeline."

🖥️ Demo: One Prompt Per Domain

1. Core/Work Items: "List my active work items in <project> for the current iteration"
2. Repositories: "List open pull requests I'm a reviewer on in <project>"
3. Pipelines: "Show the status of the last 5 builds for the <pipeline> definition"
4. Search: "Search the code for TODO: security across <project>"
5. Show the Select Tools picker and how disabling a domain changes what the agent can do

Discussion Points

• Which two or three domains would deliver the most value to your team on day one?
• Are there domains you would deliberately not load for safety or noise reduction?
• How could "summarise my sprint" or "explain this build failure" change your daily standups?

☕ Break (5 min)

4. Hands-On: Driving a Test Azure DevOps Project (15 min)

Key Points

This section is hands-on — attendees work through the lab against a sandbox project they provision and seed. The lab guide (ado-mcp-LAB.md) contains the full step-by-step exercises; this section frames what to practise and what "good" looks like.

What You'll Do

1. Provision a sandbox: create a free Azure DevOps organisation (Entra-connected) and a project named mcp-sandbox
2. Seed content: import a sample repo, create a few work items, and run a simple pipeline so there is real data to query
3. Connect the server: drop in .vscode/mcp.json (Remote first; Local as fallback) and authenticate
4. Read workflows: list projects, list your work items, inspect a PR, fetch a build log
5. Write workflows (with confirmation): create a bug, add a child task, open a draft PR, create a wiki page

Effective Prompting Patterns

• Be specific about scope: name the project and team — "in mcp-sandbox, for the mcp-sandbox Team"
• Ask for structure: "…and return the results as a table with ID, title, state, assignee"
• Chain naturally: "Now create a child task under that bug for the unit test."
• Set a project default (Local server) via env vars so you stop repeating the project name:

"env": {
  "ado_mcp_project": "mcp-sandbox",
  "ado_mcp_team": "mcp-sandbox Team"
}

Recommended Copilot Instruction

Add this line to .github/copilot-instructions.md so the agent reliably reaches for the server:

This project uses Azure DevOps. Always check to see if the Azure DevOps MCP server has a tool relevant to the user's request.

Success Criteria

• ✅ The agent lists your sandbox project and your work items without copy/paste
• ✅ You created a work item and a child item through natural language (with confirmation)
• ✅ You retrieved a build log and had the agent explain a failure
• ✅ You scoped the server to a subset of domains and observed the change in available tools

Discussion Points

• How accurate were the agent's results? Where did specificity in the prompt help?
• Did the write-confirmation flow feel safe enough for everyday use?
• What instruction or default would you standardise across your repos?

5. MCP vs REST API — Comprehensive Comparison (15 min)

Key Points

This is the heart of the workshop. The MCP server and the REST API are complementary, not competing. The MCP server is a thin, curated, conversational layer; the REST API is the complete, deterministic, programmable surface beneath it.

Conceptual Difference

Detailed Comparison Matrix

Pros, Cons & Requirements

Decision Flow

graph TD
    Start[Need to interact with Azure DevOps] --> Q1{Interactive or<br/>unattended?}
    Q1 -->|Interactive in IDE| Q2{Operation exists<br/>as a tool?}
    Q1 -->|Unattended automation| REST[Use the REST API]
    Q2 -->|Yes| MCP[Use the MCP Server]
    Q2 -->|No, full control| REST
    MCP --> Hybrid{Need determinism<br/>or bulk scale?}
    Hybrid -->|Yes| REST
    Hybrid -->|No| Done[Stay in the agent]

The Hybrid Reality

Most teams use both: the MCP server for day-to-day interactive work inside the IDE (triage, review, debugging, documentation), and the REST API for scheduled jobs, governance automation, bulk operations, and anything that must be deterministic and auditable. Remember the server is built on the REST API — choosing MCP never closes the door to REST.

💡 Rule of thumb: If a human is in the loop and exploring, prefer MCP. If a machine runs it on a schedule and must not vary, prefer REST.

Discussion Points

• Which of your current Azure DevOps integrations are genuinely automation (REST) vs. interactive (MCP)?
• Are there scripts your team maintains today that would be better as on-demand agent prompts?
• Where is determinism non-negotiable for you — and therefore firmly REST territory?

6. Governance, Security & Best Practices (10 min)

Key Points

The server is powerful, so scope and guardrails matter. Three controls do most of the work: read-only mode, toolset/tool filtering, and least-privilege identity.

Scoping Controls

Example — a read-only, repos-and-wiki-only remote server:

{
  "servers": {
    "ado-remote-mcp": {
      "url": "https://mcp.dev.azure.com/{organization}",
      "type": "http",
      "headers": {
        "X-MCP-Toolsets": "repos,wiki",
        "X-MCP-Readonly": "true"
      }
    }
  },
  "inputs": []
}

Security Practices

• Least privilege by identity: the server acts as the signed-in user — grant people only the Azure DevOps access they should have, and the server inherits those limits.
• Prefer read-only for analysis, reporting, and exploration scenarios; reserve write-enabled configs for the people and repos that need them.
• Approve writes deliberately: keep tool-confirmation prompts on; never blanket-approve write tools.
• Beware prompt injection: build logs, PR comments, wiki text, and work-item descriptions are untrusted content. The server applies spotlighting to external content, but treat agent output that originates from such data with care, and never let it auto-trigger sensitive writes.
• Mind token cost: scoping toolsets reduces both noise and token consumption.
• Commit sensible defaults: a checked-in .vscode/mcp.json plus a .github/copilot-instructions.md line gives every teammate a consistent, governed starting point.

Important: MCP does not bypass Azure DevOps permissions, branch policies, or audit logging. A write performed via an MCP tool is the same operation — subject to the same policies — as one performed in the portal or via REST.

Discussion Points

• Which teams or repos should run read-only by default?
• What is your policy for write-enabled tools and confirmation prompts?
• How will you handle untrusted content (logs, comments) flowing into agents?

7. When to Use Which & Wrap-Up (5 min)

Key Takeaways

• The Azure DevOps MCP Server makes your projects conversational for AI agents — it is a thin, curated layer over the REST API.
• Start with the Remote server (preview) for the fastest path; use Local for PAT auth, other clients, or domain filtering.
• Authentication is as the signed-in user — permissions, policies, and audit still apply.
• Reach for MCP when a human is interactively exploring; reach for REST when a machine runs it unattended and must be deterministic.
• Govern with read-only mode, toolset scoping, and least-privilege identity.

When to Choose

Immediate Next Steps

1. Connect the Remote server to a sandbox org and run five read prompts
2. Add the recommended line to .github/copilot-instructions.md
3. Decide your team's default toolset scope and whether to start read-only
4. Identify one interactive workflow to move to MCP and one automation to keep on REST
5. Complete the lab (ado-mcp-LAB.md) end-to-end

Discussion Points

• What's the first workflow your team will move into the agent?
• Who owns the team's .vscode/mcp.json defaults and governance settings?
• What would make you comfortable enabling write tools more broadly?

Appendix

Workshop Materials

Key URLs

Tool Domains Reference

Glossary

Post-Workshop Actions

• Connect the Remote server to a sandbox org and validate five read prompts
• Add the Azure DevOps line to .github/copilot-instructions.md
• Agree the team's default toolset scope and read-only policy
• Document one interactive workflow moved to MCP and one automation kept on REST
• Complete the hands-on lab end-to-end
• Decide whether .vscode/mcp.json is committed as a team default

Workshop guide for the Azure DevOps MCP Server Workshop