🚀 Getting Started with Azure DevOps MCP Server

This guide will help you get started with the Azure DevOps MCP Server in different environments.

Prerequisites
Authentication Methods
Getting started with Visual Studio Code & GitHub Copilot
Getting started with Visual Studio 2022 & GitHub Copilot
Getting started with GitHub Copilot CLI
Getting started with Claude Code
Getting started with Claude Desktop
Getting started with Cursor
Getting started with Opencode
Getting started with Kilocode
Optimizing Your Experience

🕐 Prerequisites

For the best experience, use Visual Studio Code and GitHub Copilot.

Before you begin, make sure you have:

For Visual Studio Code

Install VS Code or VS Code Insiders
Install Node.js 20+
Open VS Code in an empty folder

For Visual Studio 2022

Install VS Studio 2022 version 17.14 or later
Open a project in Visual Studio

🔐 Authentication Methods

The Azure DevOps MCP Server supports several authentication methods. Pass the desired method via the --authentication (-a) flag in your mcp.json configuration.

Method	Flag value	Environment variable	Best for
Interactive (default)	`interactive`	—	Local development, first-time setup
Azure CLI	`azcli`	—	Workstations already signed in with `az login`
Environment variable (bearer)	`envvar`	`ADO_MCP_AUTH_TOKEN`	CI/CD, automation
Personal Access Token	`pat`	`PERSONAL_ACCESS_TOKEN`	CI/CD, service accounts, non-interactive environments

🔵 Interactive (Default)

Opens a browser window for Microsoft account login. No extra configuration needed — this is the default when --authentication is omitted.

{
  "servers": {
    "ado": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "<your-org>"]
    }
  }
}

🟢 Azure CLI (`azcli`)

Uses the token from an active az login session. Requires the Azure CLI to be installed and signed in.

{
  "servers": {
    "ado": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "<your-org>", "--authentication", "azcli"]
    }
  }
}

🟡 Environment Variable — Bearer Token (`envvar`)

Reads a raw bearer token from the ADO_MCP_AUTH_TOKEN environment variable. Useful when another tool or pipeline injects the token at runtime.

Set the environment variable:

export ADO_MCP_AUTH_TOKEN="<your-azure-devops-bearer-token>"

Configure .vscode/mcp.json:

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

🔑 Personal Access Token (`pat`)

Authenticates using an Azure DevOps Personal Access Token (PAT). The token must be stored in the PERSONAL_ACCESS_TOKEN environment variable as a base64-encoded string.

PAT format

The value stored in PERSONAL_ACCESS_TOKEN must be the base64 encoding of <email>:<pat>, where <email> is any non-empty string (the Azure DevOps API only uses the token portion) and <pat> is the raw PAT you copied from Azure DevOps.

`.vscode/mcp.json` configuration

{
  "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}", "--authentication", "pat"],
      "env": {
        "PERSONAL_ACCESS_TOKEN": "<base64encoded email:pat>"
      }
    }
  }
}

Security note: Avoid hard-coding the PAT value directly in mcp.json when committing to source control. Prefer injecting it via an environment variable set outside the config file, or use a secrets manager.

🍕 Installation Options

➡️ Visual Studio Code & GitHub Copilot

For the best experience, use Visual Studio Code and GitHub Copilot.

🧨 Install from Public Feed (Recommended)

This installation method is the easiest for all users of Visual Studio Code.

🎥 Watch this quick start video to get up and running in under two minutes!

Steps

In your project, add a .vscode\mcp.json file with the following content:

{
  "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 the file, then click 'Start'.

In chat, switch to Agent Mode.

Click "Select Tools" and choose the available tools.

💥 We strongly recommend creating a .github\copilot-instructions.md in your project and copying the contents from this copilot-instructions.md file. This will enhance your experience using the Azure DevOps MCP Server with GitHub Copilot Chat.

Start using it

Open GitHub Copilot in VS Code and switch to Agent mode.
Start the Azure DevOps MCP Server.
The server appears in the tools list.
Try prompts like "List ADO projects".

Using Token Authentication via Environment Variables

For automated scenarios or when you want to use a token stored in an environment variable, you can use the envvar authentication type:

Set your token in the ADO_MCP_AUTH_TOKEN environment variable:
```
export ADO_MCP_AUTH_TOKEN="your-azure-devops-token"
```

Update your .vscode/mcp.json to use token authentication:

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

This approach is particularly useful for CI/pipeline scenarios or when you want to avoid interactive authentication and use another credential source.

🛠️ Install from Source (Dev Mode)

This installation method is recommended for advanced users and contributors who want immediate access to the latest updates from the main branch. It is ideal if you are developing new tools, enhancing existing features, or maintaining a custom fork.

Note: For most users, installing from the public feed is simpler and preferred. Use the source installation only if you need the latest changes or are actively contributing to the project.

Steps

Clone the repository.

Install dependencies:

npm install

Edit or add .vscode/mcp.json:

{
  "inputs": [
    {
      "id": "ado_org",
      "type": "promptString",
      "description": "Azure DevOps organization's name  (e.g. 'contoso')"
    }
  ],
  "servers": {
    "ado": {
      "type": "stdio",
      "command": "mcp-server-azuredevops",
      "args": ["${input:ado_org}"]
    }
  }
}

Start the Azure DevOps MCP Server.

In chat, switch to Agent Mode.

Click "Select Tools" and choose the available tools.

💥 We strongly recommend creating a .github\copilot-instructions.md in your project and copying the contents from this copilot-instructions.md file. This will help you get the best experience using the Azure DevOps MCP Server in GitHub Copilot Chat.

➡️ Visual Studio 2022 & GitHub Copilot

🧨 Install from Public Feed (Recommended)

This installation method is the easiest for all users of Visual Studio 2022.

🎥 Watch this quick start video to get up and running in under two minutes!

Steps

Add a .mcp.json file to the solution folder with the following content:

{
  "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 the file.

Add your organization name by clicking on the input option.

Open Copilot chat and switch to Agent Mode.

Click the "Tools" icon and choose the available tools.

💥 We strongly recommend creating a .github\copilot-instructions.md in your project and copying the contents from this copilot-instructions.md file. This will enhance your experience using the Azure DevOps MCP Server with GitHub Copilot Chat.

Start using it

Prerequisites: Visual Studio 2022 v17.14+, Agent mode enabled in Tools > Options > GitHub > Copilot > Copilot Chat.

Switch to Agent mode in the Copilot Chat window.
Enter your Azure DevOps organization name.
Select desired ado tools.
Try prompts like "List ADO projects".

For more details, see Visual Studio MCP Servers documentation and the Getting Started Video.

💻 Using MCP Server with GitHub Copilot CLI

Use the Copilot CLI to interactively add the MCP server:

/mcp add

Alternatively, create or edit the configuration file ~/.copilot/mcp-config.json and add:

{
  "mcpServers": {
    "ado": {
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "{Contoso}"],
      "tools": ["*"]
    }
  }
}

Replace {Contoso} with your Azure DevOps organization name.

For more information, see the Copilot CLI documentation.

🤖 Using MCP Server with Claude Code

See https://docs.anthropic.com/en/docs/claude-code/mcp for general guidance on adding MCP Server to Claude Code experience.

For the Azure DevOps MCP Server, use the following command:

claude mcp add azure-devops -- npx -y @azure-devops/mcp Contoso

Replace Contoso with your own organization name

✴️ Using MCP Server with Claude Desktop

Open Claude Desktop and navigate to File > Settings > Developer. Click Edit Config.

Open the configuration file in your preferred editor (e.g., VS Code) and add the following JSON:

{
  "mcpServers": {
    "ado": {
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "{Contoso}"]
    }
  }
}

Replace {Contoso} with your Azure DevOps organization name. Save the file and perform a hard restart of the Claude app.

Start a new chat, then click the Search and Tools icon. The ado toolset should now be available.

You’re ready to start using the Azure DevOps MCP Server in Claude Desktop. Try a simple request such as: get list of ado projects.

For additional guidance on Claude Desktop, see the Quickstart.

🍇 Using MCP Server with Cursor

To integrate the Azure DevOps MCP Server with Cursor, create a .cursor\mcp.json file and add your Azure DevOps organization to the mcpServers list.

{
  "mcpServers": {
    "ado": {
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "{Contoso}"]
    }
  }
}

Replace {Contoso} with your actual Azure DevOps organization name.

Save the file, and when Cursor detects the MCP Server, click Enable.

Start the Azure DevOps MCP Server

Open the terminal and start the MCP Server with:

npx -y @azure-devops/mcp {Contoso}

Replace Contoso with your Azure DevOps organization.

You can now use the Azure DevOps MCP Server tools directly in chat.

📽️ Azure DevOps MCP Server: Getting started with Cursor

🟢 Using MCP Server with Opencode

Add the Azure DevOps MCP server to your Opencode config file.

Config file location:

macOS / Linux: ~/.config/opencode/opencode.json

Add the azure-devops entry under the mcp key:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "azure-devops": {
      "type": "local",
      "command": ["npx", "-y", "@azure-devops/mcp", "<your-org>"],
      "enabled": true
    }
  }
}

Replace <your-org> with your Azure DevOps organization name (e.g. contoso).

Note: On first use, Opencode will trigger browser-based Microsoft account login.

Tip: Limit loaded tools using domain filtering by appending -d flags to the command:
"command": ["npx", "-y", "@azure-devops/mcp", "<your-org>", "-d", "core", "work", "work-items"]
Available domains: core, work, work-items, repositories, wiki, pipelines, search, test-plans, advanced-security

For more on Opencode MCP configuration, see the Opencode MCP docs.

⬛ Using MCP Server with Kilocode

Kilocode supports MCP servers at two levels — global (all workspaces) or project (repo-specific).

Option A — Global config

Open the Kilocode pane → click the ⚙️ icon → Agent Behaviour → MCP Servers
Click Edit Global MCP to open mcp_settings.json
Add the azure-devops entry:

{
  "mcpServers": {
    "azure-devops": {
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "<your-org>"]
    }
  }
}

Option B — Project config

Create .kilocode/mcp.json in your project root with the same content as above. This file can be committed to version control to share the setup with your team.

Windows users: Wrap the command for the Windows Command Prompt:

{
  "mcpServers": {
    "azure-devops": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@azure-devops/mcp", "<your-org>"]
    }
  }
}

Replace <your-org> with your Azure DevOps organization name. On first use, a browser window will open for Microsoft account login.

For more on Kilocode MCP configuration, see the Kilocode MCP docs.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🚀 Getting Started with Azure DevOps MCP Server

🕐 Prerequisites

For Visual Studio Code

For Visual Studio 2022

🔐 Authentication Methods

🔵 Interactive (Default)

🟢 Azure CLI (`azcli`)

🟡 Environment Variable — Bearer Token (`envvar`)

🔑 Personal Access Token (`pat`)

PAT format

`.vscode/mcp.json` configuration

🍕 Installation Options

➡️ Visual Studio Code & GitHub Copilot

🧨 Install from Public Feed (Recommended)

Steps

Start using it

Using Token Authentication via Environment Variables

🛠️ Install from Source (Dev Mode)

Steps

➡️ Visual Studio 2022 & GitHub Copilot

🧨 Install from Public Feed (Recommended)

Steps

Start using it

💻 Using MCP Server with GitHub Copilot CLI

🤖 Using MCP Server with Claude Code

✴️ Using MCP Server with Claude Desktop

🍇 Using MCP Server with Cursor

Start the Azure DevOps MCP Server

🟢 Using MCP Server with Opencode

⬛ Using MCP Server with Kilocode

Option A — Global config

Option B — Project config

FilesExpand file tree

GETTINGSTARTED.md

Latest commit

History

GETTINGSTARTED.md

File metadata and controls

🚀 Getting Started with Azure DevOps MCP Server

🕐 Prerequisites

For Visual Studio Code

For Visual Studio 2022

🔐 Authentication Methods

🔵 Interactive (Default)

🟢 Azure CLI (azcli)

🟡 Environment Variable — Bearer Token (envvar)

🔑 Personal Access Token (pat)

PAT format

.vscode/mcp.json configuration

🍕 Installation Options

➡️ Visual Studio Code & GitHub Copilot

🧨 Install from Public Feed (Recommended)

Steps

Start using it

Using Token Authentication via Environment Variables

🛠️ Install from Source (Dev Mode)

Steps

➡️ Visual Studio 2022 & GitHub Copilot

🧨 Install from Public Feed (Recommended)

Steps

Start using it

💻 Using MCP Server with GitHub Copilot CLI

🤖 Using MCP Server with Claude Code

✴️ Using MCP Server with Claude Desktop

🍇 Using MCP Server with Cursor

Start the Azure DevOps MCP Server

🟢 Using MCP Server with Opencode

⬛ Using MCP Server with Kilocode

Option A — Global config

Option B — Project config

🟢 Azure CLI (`azcli`)

🟡 Environment Variable — Bearer Token (`envvar`)

🔑 Personal Access Token (`pat`)

`.vscode/mcp.json` configuration