Workshop Section: Hands-On — Driving a Test Azure DevOps Project

Objective

Create an Entra-connected Azure DevOps organisation and a project named mcp-sandbox, then seed it with a repo, work items, and a pipeline so there is real data for the agent to query.

Steps

Step 1: Create an organisation and project

1. Go to https://dev.azure.com and sign in with your Microsoft Entra account.
2. Create a new organisation (or reuse an existing Entra-connected one).
3. Create a new project named mcp-sandbox (Visibility: Private; Work item process: Agile).

Step 2: Seed a repository

Option A — import a public sample (fastest):

1. In mcp-sandbox, open Repos → Import a repository.
2. Clone URL:

https://github.com/MicrosoftDocs/pipelines-javascript.git

Option B — initialise with a README:

1. In Repos, choose Initialize with a README.md and a .gitignore.

Step 3: Seed work items

1. Open Boards → Work items → New Work Item.
2. Create a User Story: "As a user, I can sign in".
3. Create two Bugs: "Login returns 500" and "Reset-password email not sent".
4. Assign at least one item to yourself and set its iteration to the current sprint.

Step 4: Seed a pipeline

1. Open Pipelines → New pipeline → Azure Repos Git → select your repo.
2. Choose Starter pipeline, then Save and run to produce at least one build.

Tip: To seed a richer environment quickly, the Azure DevOps Demo Generator (https://learn.microsoft.com/en-us/azure/devops/demo-gen) can populate a project with sample work items, repos, and pipelines.

Success Criteria

• ✅ A private mcp-sandbox project exists in an Entra-connected org
• ✅ The project has a repo with files
• ✅ At least three work items exist, one assigned to you in the current iteration
• ✅ At least one pipeline build has completed (success or failure both fine)

Workshop Section: Setup, Installation & Authentication

Objective

Connect the Remote MCP Server to your sandbox, authenticate with Entra ID, and confirm the agent can reach Azure DevOps. Then connect the Local server as an alternative.

Steps

Step 1: Open your project folder in VS Code

Open any local folder in VS Code (it does not need to be the sandbox repo).

Step 2: Configure the Remote server

Create .vscode/mcp.json with the following content, replacing {organization} with your org name:

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

Step 3: Start the server and authenticate

1. Open the MCP view (or run the MCP: List Servers command) and Start ado-remote-mcp.
2. When prompted, sign in with your Microsoft Entra account.

Step 4: Run your first prompt

Open Copilot Chat, switch to Agent Mode, and run:

List the projects in my Azure DevOps organization

Approve the tool call when prompted. You should see mcp-sandbox in the results.

Step 5: Add a Copilot instruction

Create .github/copilot-instructions.md with:

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

Step 6 (Optional): Configure the Local server

Replace .vscode/mcp.json with the Local configuration to compare:

{
  "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}"]
    }
  }
}

Start it, enter your org name when prompted, and re-run the List ADO projects prompt.

Success Criteria

• ✅ The Remote server is running and authenticated
• ✅ The agent returns your project list, including mcp-sandbox
• ✅ .github/copilot-instructions.md contains the Azure DevOps line
• ✅ (Optional) The Local server connects and returns the same results

Workshop Section: Capability Tour — Tools by Domain

Objective

Exercise read tools across multiple domains to query your sandbox in natural language. Notice how specificity in the prompt improves the result.

Steps

Step 1: Work items

In mcp-sandbox, list my active work items in the current iteration as a table with ID, type, title, state, and assignee.

Step 2: Repositories & pull requests

List the repositories in mcp-sandbox, then list the branches in the first repository.

If you have any pull requests, also try:

Show the details and linked work items for the most recent pull request in mcp-sandbox.

Step 3: Pipelines

List the pipeline definitions in mcp-sandbox and show the status of the last 5 builds.

Then inspect a build log:

Get the log for the most recent build in mcp-sandbox and summarise what happened.

Step 4: Search

Search the code in mcp-sandbox for "TODO" and list the files and line numbers.

Step 5: Observe scoping

Open Select Tools in chat and note which Azure DevOps tools are available. Disable a domain (e.g. Pipelines) and re-run the Step 3 prompt — the agent should no longer have the tool.

Success Criteria

• ✅ You retrieved work items, repos/branches, pipeline status, and a build log
• ✅ At least one prompt returned a structured table you requested
• ✅ You ran a code search and got file/line results
• ✅ You observed the agent lose a capability when a domain was disabled

Workshop Section: Capability Tour — Tools by Domain

Objective

Use write tools to create and modify Azure DevOps resources through the agent, observing the confirmation prompt before each change.

Steps

Step 1: Create a bug

In mcp-sandbox, create a bug titled "Login button misaligned on mobile" with a short repro description, assigned to me.

Review and approve the tool call. Confirm the new work item ID in the result.

Step 2: Add a child task

Add a child task under that bug titled "Add responsive CSS unit test".

Step 3: Open a draft pull request

First create a branch (or ask the agent to):

In the mcp-sandbox repo, create a branch called feature/mobile-css from the default branch, then open a draft pull request from feature/mobile-css into the default branch titled "Fix mobile login layout".

Step 4: Create a wiki page

Create a wiki page at /Onboarding/MCP-Sandbox with a short description of this sandbox project and how to connect the MCP server.

Step 5: Verify in the portal

Open mcp-sandbox in the browser and confirm the bug, child task, branch/PR, and wiki page all exist.

Important: Every write tool surfaces a confirmation prompt. Read each one before approving — the agent cannot mutate your project without your explicit approval.

Success Criteria

• ✅ A bug and a linked child task were created via natural language
• ✅ A branch and a draft pull request were created
• ✅ A wiki page was created and is visible in the portal
• ✅ You reviewed and approved each write through the confirmation prompt

Workshop Section: Governance, Security & Best Practices · MCP vs REST API

Objective

Apply governance controls (read-only and toolset scoping), then run the same "list projects" operation directly against the REST API to make the MCP-vs-REST difference tangible.

Steps

Step 1: Make the server read-only (Remote)

Update .vscode/mcp.json to add headers, restart the server, and try a write:

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

Now ask the agent to create a work item. It should no longer have a write tool available.

Step 2: Compare to the REST API

Create a Personal Access Token (User settings → Personal access tokens → New Token → scope Project and Team (Read)), then run:

curl -u :YOUR_PAT "https://dev.azure.com/{organization}/_apis/projects?api-version=7.1"

Compare the experiences:

• The REST call required a token, the correct route, an api-version, and returns raw JSON you must parse.
• The MCP prompt (List ADO projects) required none of that and returned a readable summary.

Important: Treat the PAT like a password. Delete it after the lab if it is not needed, and never commit it.

Step 3: Reflect

Note one workflow from today you would keep in MCP (interactive) and one you would implement with REST (unattended/deterministic).

Success Criteria

• ✅ The read-only server refused to expose a write tool
• ✅ You scoped the server to a subset of toolsets
• ✅ You retrieved projects via the REST API and compared the experience to MCP
• ✅ You identified one MCP use case and one REST use case for your team