Skip to main content
Glama
Azure DevOps Multi-Organization MCP Server

Azure DevOps Multi-Organization MCP Server

by nikydobrev

Azure DevOps Multi-Organization MCP Server

This is a specialized Model Context Protocol (MCP) server for Azure DevOps, designed to overcome the limitations of single-organization bindings found in standard implementations.

🚀 Value Proposition & Comparison

The primary value of this implementation is Multi-Organization Support and Context Optimization.

Feature

Standard / Official AzDO MCP

This Implementation

User Value

Scope

Single Organization (bound via AZURE_DEVOPS_ORG env var)

Multi-Organization (Dynamic Routing)

Seamlessly work across org-1, org-2, and other orgs in a single chat session without restarting the server.

Authentication

Single PAT in .env

Multiple PATs in config.json

Securely manages distinct credentials for different organizations.

Context Usage

Returns raw, verbose API responses

LLM-Optimized Responses

Aggressively flattens and simplifies JSON output (e.g., removing huge log objects from list views) to prevent "Maximum Length" errors in Claude.

Tool Signature

(project, ...args)

(organization, project, ...args)

Explicit control over the target organization for every action.

Related MCP server: Azure DevOps MCP Server

🛠 Architecture

1. The Connection Manager Pattern

Instead of initializing a single connection at startup, this server uses a ConnectionManager class.

  • Lazy Loading: Connections to Azure DevOps are established only when a tool is requested.

  • Caching: Authenticated connections are cached to ensure performance for subsequent requests.

  • Routing: Every tool schema includes an organization argument. The manager uses this to look up the corresponding Personal Access Token (PAT) from config.json.

2. Modular Tool Structure

Tools are organized into separate modules for maintainability:

  • tools/organizations.ts: Organization and project discovery tools

  • tools/pipelines.ts: CI/CD pipeline operations (builds, definitions, runs, logs)

  • tools/repositories.ts: Git repository and pull request management

  • tools/common.ts: Shared utilities for enum handling and type conversions

  • tools/index.ts: Central registration orchestrator

3. Context Window Optimization

Standard Azure DevOps API responses are extremely verbose, often containing full orchestration plans, logs, and deep nesting. This implementation intercepts these responses in tools like pipelines_get_builds and pipelines_get_build_definitions to:

  • Limit Results: Defaults to top 20/50 items instead of hundreds.

  • Flatten Objects: Maps complex objects to simple key-value pairs (e.g., { requestedFor: { displayName: "User" } } becomes just the display name).

  • Strip Noise: Removes unused URLs, large configuration blobs, and system metadata.

4. Dual Transport Support

  • Stdio Transport: For local usage with Claude Desktop and VS Code (default)

  • SSE Transport: For cloud deployment with HTTP endpoints (activated via PORT env var)

📦 Configuration

1. Prerequisites

  • Node.js (v18 or higher)

  • Azure DevOps Personal Access Tokens (PAT) with appropriate permissions:

    • Code (Read): For repository and pull request operations

    • Build (Read & Execute): For pipeline and build operations

    • Project and Team (Read): For organization and project listing

2. Setup config.json

Create a config.json file in the root directory. This file maps your Organization names (as they appear in the URL, e.g., dev.azure.com/{org}) to their PATs.

{
  "org-1": "your-pat-token-here",
  "org-2": "another-pat-token-here"
}

3. Build & Run

npm install
npm run build

4. Claude Desktop Configuration (Local - Stdio)

Add the server to your claude_desktop_config.json for local usage:

{
  "mcpServers": {
    "azure-devops-multi": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-server-azure-devops-multi/dist/index.js"
      ]
    }
  }
}

5. VS Code Configuration (Local - Stdio)

Add the server to your VS Code settings for use with GitHub Copilot Chat:

  1. Open VS Code Settings (JSON)

  2. Add to github.copilot.chat.mcp.servers:

{
  "github.copilot.chat.mcp.servers": {
    "Azure DevOps Multi": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-server-azure-devops-multi/dist/index.js"
      ]
    }
  }
}

6. Cloud Deployment (HTTP/SSE)

The server supports SSE (Server-Sent Events) transport for cloud deployment:

Docker Build & Run

docker build -t azdo-mcp-server .
docker run -p 3000:3000 -v /path/to/config.json:/app/config.json azdo-mcp-server

Azure Container Apps

az containerapp create \
  --name azdo-mcp-server \
  --resource-group <your-rg> \
  --environment <your-env> \
  --image <your-acr>.azurecr.io/azdo-mcp-server:latest \
  --target-port 3000 \
  --ingress external \
  --env-vars PORT=3000

The server automatically switches to SSE transport when PORT environment variable is set, exposing:

  • GET /sse - SSE connection endpoint

  • POST /messages - Message handling endpoint

🧰 Available Tools (18 Total)

Organization & Projects (2 Tools)

  • list_organizations: View all configured organizations in config.json.

  • list_projects: List all projects within a specific organization.

Pipelines & Builds (13 Tools)

  • pipelines_get_builds: List recent builds with filtering options (optimized for context).

  • pipelines_get_build_definitions: List build definitions with query options (optimized for context).

  • pipelines_get_build_status: Get detailed report for a specific build.

  • pipelines_get_build_log: Retrieve logs for a specific build.

  • pipelines_get_build_timeline: Get timeline entries for a build.

  • pipelines_run_pipeline: Trigger a new pipeline run with parameters and variables.

  • pipelines_get_run: Get details for a specific pipeline run.

  • pipelines_list_runs: List pipeline runs with filtering options.

  • pipelines_get_run_stage: Get information about a specific stage in a pipeline run.

  • pipelines_get_run_log: Get log content for a specific pipeline run.

  • pipelines_update_build_stage: Update a stage in a build (placeholder - not yet implemented).

  • pipelines_get_definition: Get a specific build definition by ID.

  • pipelines_get_definition_yaml: Get the YAML content of a pipeline definition.

Git Repositories & Pull Requests (5 Tools)

  • git_list_repositories: List all Git repositories in a project.

  • git_get_repository: Get details for a specific repository.

  • git_get_pull_requests: Search and list pull requests with filtering options.

  • git_create_pull_request: Create a new pull request with title, description, and reviewers.

  • git_get_item: Get file or folder content from a repository with version control options.

Available Tools

18 tools
git_create_pull_requestC

Creates a new pull request in a repository

Inputs: organization (required), project (required), repositoryId (required), sourceRefName (required), +4 more.

git_get_itemC

Gets a file or folder from a Git repository with optional content and version control

Inputs: organization (required), project (required), repositoryId (required), path (required), +9 more.

git_get_pull_requestC

Gets details of a specific pull request by ID

Inputs: organization (required), project (required), pullRequestId (required).

git_get_pull_requestsC

Gets a list of pull requests in a repository with filtering options

Inputs: organization (required), project (required), repositoryId (required), status, +5 more.

git_list_repositoriesC

Lists all Git repositories in a project

Inputs: organization (required), project (required), includeHidden.

list_organizationsB

Lists all available Azure DevOps organizations from the configuration

Inputs: no named parameters.

list_projectsB

Lists all projects in an Azure DevOps organization

Inputs: organization (required).

pipelines_get_build_changesC

Gets the code changes (commits) associated with a build

Inputs: organization (required), project (required), buildId (required), continuationToken, +2 more.

pipelines_get_build_definition_revisionsB

Gets the revision history of a build definition

Inputs: organization (required), project (required), definitionId (required).

pipelines_get_build_definitionsC

Gets a list of build definitions (pipeline configurations) in a project

Inputs: organization (required), project (required), repositoryId, repositoryType, +14 more.

pipelines_get_build_logC

Gets the list of log files for a build

Inputs: organization (required), project (required), buildId (required).

pipelines_get_build_log_by_idC

Gets the content of a specific build log file by ID

Inputs: organization (required), project (required), buildId (required), logId (required), +2 more.

pipelines_get_buildsC

Gets a list of builds (pipeline runs) with filtering options

Inputs: organization (required), project (required), definitions, queues, +18 more.

pipelines_get_build_statusC

Gets the status report for a build

Inputs: organization (required), project (required), buildId (required).

pipelines_get_runC

Gets details of a specific pipeline run

Inputs: organization (required), project (required), pipelineId (required), runId (required).

pipelines_list_runsC

Lists all runs for a specific pipeline

Inputs: organization (required), project (required), pipelineId (required).

pipelines_run_pipelineC

Triggers a new pipeline run with optional parameters and variables

Inputs: organization (required), project (required), pipelineId (required), pipelineVersion, +6 more.

pipelines_update_build_stageC

Updates the status of a build stage (cancel or retry)

Inputs: organization (required), project (required), buildId (required), stageName (required), +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 18 tools

    Disambiguation4/5

    Most tools have distinct purposes, with clear separation between Git operations (pull requests, repositories) and pipeline operations (builds, runs, logs). However, some pipeline tools could cause confusion: 'pipelines_get_build_log' and 'pipelines_get_build_log_by_id' overlap in purpose, and 'pipelines_get_builds' vs 'pipelines_list_runs' might be ambiguous without careful reading of descriptions. Overall, the descriptions help clarify, but there is minor overlap in the pipeline logging and listing areas.

    Naming Consistency5/5

    Tool names follow a highly consistent pattern throughout. Git tools use 'git_' prefix with verb_noun format (e.g., 'git_create_pull_request'), pipeline tools use 'pipelines_' prefix with verb_noun format (e.g., 'pipelines_get_builds'), and organizational tools use 'list_' prefix (e.g., 'list_organizations'). All names use snake_case consistently, with clear and predictable structures that enhance readability and agent usability.

    Tool Count4/5

    With 18 tools, the count is slightly high but reasonable for covering Azure DevOps operations across Git, pipelines, and organizations. It provides comprehensive functionality without being overwhelming. The tools are well-scoped to the server's purpose, though it borders on the heavier side (16-25 range), which is acceptable given the domain complexity.

    Completeness4/5

    The tool set offers strong coverage for Git and pipeline operations, including create, get, list, update, and run actions. However, there are minor gaps: for Git, tools like update or delete for pull requests or repositories are missing, and for pipelines, operations like creating or deleting definitions might be lacking. These gaps are not critical but could limit some agent workflows, making the surface mostly complete with room for enhancement.

    Related MCP Connectors

    Related MCP Servers