Skip to content

Azure DevOps MCP Configuration Guide for Cursor

Introduction

This guide provides step-by-step instructions for configuring the Azure DevOps Model Context Protocol (MCP) server in Cursor. The Azure DevOps MCP enables seamless integration between Azure DevOps and Cursor's AI assistant, allowing you to query work items, create pull requests, manage pipelines, and interact with your Azure DevOps organization directly from Cursor.

GitHub Repository: fsabatini82/azure-devops-mcp

Table of Contents

  1. Prerequisites
  2. Overview
  3. Step-by-Step Configuration
  4. Validation & Testing
  5. Troubleshooting
  6. Security Best Practices
  7. Usage Examples
  8. References

Prerequisites

Before starting the configuration, ensure you have:

  • Cursor IDE installed and updated to the latest version
  • Node.js (version 18 or later) installed (required for npx command)
  • Azure DevOps Account with an active organization
  • Personal Access Token (PAT) from Azure DevOps (see Step 2)
  • Network access to Azure DevOps APIs (dev.azure.com)

Overview

The Azure DevOps MCP server runs as a Model Context Protocol server that exposes Azure DevOps APIs to Cursor's AI assistant. This allows you to:

  • Query and manage work items (Epics, Features, User Stories, Tasks, Bugs)
  • Create and manage pull requests
  • View and trigger pipelines
  • Manage repositories and branches
  • Search code, work items, and wikis
  • And much more!

The MCP server is installed via npm and configured through Cursor's mcp.json configuration file.

Step-by-Step Configuration

Step 1: Locate Cursor MCP Configuration File

The MCP configuration file is located at:

Windows: 

C:\Users\<YourUsername>\.cursor\mcp.json

macOS/Linux: 

~/.cursor/mcp.json

If the file doesn't exist, create it with the following structure:

{
  "mcpServers": {}
}

Step 2: Create Azure DevOps Personal Access Token (PAT)

  1. Navigate to Azure DevOps:
  2. Go to https://dev.azure.com

  3. Sign in to your account

  4. Create Personal Access Token:

  5. Click on your profile icon (top right)
  6. Select "Personal access tokens" or go directly to: 
    https://dev.azure.com/<your-org>/_usersSettings/tokens

  7. Click "New Token" or "+ New Token"

  8. Configure Token:

  9. Name: Give it a descriptive name (e.g., "Cursor MCP Access")
  10. Organization: Select your organization (or "All accessible organizations")
  11. Expiration: Set expiration date (recommended: 90 days or custom)

  12. Scopes: Select the following scopes (minimum required):

    • Code (Read & Write) - for repository and pull request operations
    • Work Items (Read & Write) - for work item management
    • Build (Read & Execute) - for pipeline operations
    • Project and Team (Read) - for project and team queries
    • Wiki (Read & Write) - for wiki operations

  13. Create and Copy Token:

  14. Click "Create"
  15. IMPORTANT: Copy the token immediately - you won't be able to see it again!
  16. Store it securely (we'll use it in Step 4)

Step 3: Understand the Configuration Structure

The Azure DevOps MCP uses npm package @fsabatini82/azure-devops-mcp and runs via npx. The configuration requires:

  • Server name: A unique identifier (e.g., "ado")
  • Command: npx (Node Package eXecute)
  • Arguments: Package name, organization name, and authentication method
  • Environment variables: Personal Access Token

Step 4: Add Azure DevOps MCP Configuration

Open your mcp.json file and add the following configuration inside the mcpServers object:

{
  "mcpServers": {
    "ado": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@fsabatini82/azure-devops-mcp",
        "<your-organization-name>",
        "-a",
        "pat"
      ],
      "env": {
        "AZDO_PAT": "<your-personal-access-token>"
      }
    }
  }
}

Configuration Parameters:

  • "ado" - Server name identifier (you can change this to any name you prefer)
  • "type": "stdio" - Communication method (standard input/output)
  • "command": "npx" - Command to run the package
  • "-y" - Auto-accept npm package installation (non-interactive)
  • "@fsabatini82/azure-devops-mcp" - The npm package name
  • "<your-organization-name>" - Replace with your Azure DevOps organization name (e.g., "dmitrykhaymov")
  • "-a", "pat" - Authentication method (Personal Access Token)
  • "AZDO_PAT" - Environment variable name for the PAT
  • "<your-personal-access-token>" - Replace with the PAT you created in Step 2

Example Configuration:

{
  "mcpServers": {
    "ado": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@fsabatini82/azure-devops-mcp",
        "dmitrykhaymov",
        "-a",
        "pat"
      ],
      "env": {
        "AZDO_PAT": "FLreFAzQ7hrDgS100Hv9Jcn5AcdcyDE7L5693PoAvK1CLCdW2wQiJQQJ99BJACAAAAAAAAAAAAASAZDO4RRS"
      }
    }
  }
}

Step 5: Save Configuration File

  1. Save the mcp.json file
  2. Ensure proper JSON syntax (use a JSON validator if needed)
  3. Restart Cursor to load the new configuration

Validation & Testing

Method 1: Restart Cursor

  1. Close Cursor completely
  2. Reopen Cursor
  3. The MCP server should automatically start when Cursor initializes

Method 2: Check MCP Server Status

In Cursor, you can verify the MCP server is running by:

  1. Opening the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
  2. Looking for MCP-related commands or indicators
  3. Trying to use Azure DevOps functionality in a chat

Method 3: Test with a Simple Query

Try asking Cursor's AI assistant something like:

  • "List all projects in my Azure DevOps organization"
  • "Show me work items assigned to me"
  • "What pipelines are available in my project?"

If the MCP server is configured correctly, Cursor should be able to query Azure DevOps and return results.

Method 4: Check for Errors

  • Open Cursor's developer console or logs to check for any MCP-related errors
  • Look for connection issues or authentication errors
  • Verify Node.js and npm are accessible from the command line

Troubleshooting

Issue 1: MCP Server Not Starting

Symptoms: - Cursor doesn't recognize Azure DevOps commands - No MCP functionality available

Solutions: - Verify Node.js is installed: Run node --version and npx --version in terminal - Check JSON syntax in mcp.json (use a JSON validator) - Ensure the configuration file is saved in the correct location - Restart Cursor completely

Issue 2: Authentication Errors

Symptoms: - "Unauthorized" or "401" errors - "Invalid token" messages

Solutions: - Verify your PAT is correct and hasn't expired - Check that the PAT has the required scopes (see Step 2) - Ensure the organization name in the config matches your Azure DevOps organization - Regenerate the PAT if necessary

Issue 3: Connection Timeouts

Symptoms: - Requests timing out - "Network error" messages

Solutions: - Check your internet connection - Verify firewall/proxy settings allow access to dev.azure.com - Ensure your organization URL is accessible from your network

Issue 4: Package Installation Issues

Symptoms: - npx command fails - Package not found errors

Solutions: - Ensure npm is properly configured: npm config get registry - Check if you're behind a corporate proxy (may need npm proxy configuration) - Try running npx -y @fsabatini82/azure-devops-mcp manually in terminal to test - Clear npm cache: npm cache clean --force

Issue 5: Organization Name Mismatch

Symptoms: - "Organization not found" errors - Cannot connect to Azure DevOps

Solutions: - Verify your organization name: - If your Azure DevOps URL is https://dev.azure.com/mycompany, the organization name is mycompany - If your URL is https://mycompany.visualstudio.com, check the new URL format - Ensure the organization name in mcp.json matches exactly (case-sensitive in some cases)

Issue 6: Permission Errors

Symptoms: - Can read but cannot write/create items - "Forbidden" errors

Solutions: - Regenerate PAT with additional scopes (see Step 2) - Verify your Azure DevOps account has necessary permissions in the organization/project - Check project-level permissions if working with specific projects

Security Best Practices

1. Personal Access Token Security

  • Never commit mcp.json to version control - Add it to .gitignore
  • Use token expiration dates - Set PATs to expire after a reasonable period (90 days recommended)
  • Regularly rotate tokens - Generate new PATs periodically and update configuration
  • Use minimal required scopes - Only grant the permissions needed for your use case
  • Revoke unused tokens - Remove old or unused PATs from Azure DevOps

2. File Permissions

  • Ensure mcp.json has restricted file permissions (Windows: only your user account)
  • On Linux/macOS: chmod 600 ~/.cursor/mcp.json

3. Environment Variables

  • The PAT is stored as an environment variable in the config file
  • Consider using system environment variables for production environments
  • Never share your PAT or configuration file

4. Network Security

  • Use HTTPS only (default for Azure DevOps)
  • Be cautious when using public networks
  • Consider VPN for additional security in corporate environments

Usage Examples

Once configured, you can use Azure DevOps MCP functionality in Cursor's chat. Here are some examples:

Work Items

"List all active work items in project 'KabAcademy AI'"
"Create a new task in project 'KabAcademy AI'"
"Show me work items assigned to Dmitry Khaymov"
"Update work item 2447 with a new description"

Pull Requests

"List all open pull requests in repository 'KabAcademy.AI.Bot'"
"Create a pull request from branch 'feature/new-feature' to 'main'"
"Show me comments on pull request #123"

Pipelines

"List all pipelines in project 'KabAcademy AI'"
"Trigger pipeline 'Build and Deploy'"
"Show me the status of the latest build"

Repositories

"List all repositories in project 'KabAcademy AI'"
"Show me branches in repository 'KabAcademy.AI.Bot'"
"Create a new branch 'feature/my-feature' from 'main'"

Queries

"Search for work items with title containing 'metrics'"
"Find all bugs created in the last week"
"Show me all epics in Sprint 1"

References

Official Resources

Azure DevOps API Reference

Appendix: Complete Configuration Example

Here's a complete example of the mcp.json file with Azure DevOps MCP configured:

{
  "mcpServers": {
    "ado": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@fsabatini82/azure-devops-mcp",
        "dmitrykhaymov",
        "-a",
        "pat"
      ],
      "env": {
        "AZDO_PAT": "YOUR_PERSONAL_ACCESS_TOKEN_HERE"
      }
    }
  }
}

Important Notes: - Replace dmitrykhaymov with your actual Azure DevOps organization name - Replace YOUR_PERSONAL_ACCESS_TOKEN_HERE with your actual PAT - Keep the configuration file secure and never commit it to version control

Changelog

  • 2025-10-30 - Initial guide created based on troubleshooting and setup experience

Support

If you encounter issues not covered in this guide:

  1. Check the GitHub repository for known issues
  2. Review Azure DevOps MCP package documentation
  3. Verify your Azure DevOps account and permissions
  4. Check Cursor's MCP documentation for general MCP troubleshooting

Last Updated: October 30, 2025