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.

🛠 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.