Azure Devops MCP Remote

Azure DevOps MCP Server

Conecte assistentes de IA (GitHub Copilot, Claude, Cursor) ao seu Azure DevOps — work items, repositórios, pipelines, wikis e mais.

Este servidor implementa o protocolo MCP (Model Context Protocol) para Azure DevOps. Isso permite que qualquer assistente de IA compatível com MCP leia e modifique seus projetos no Azure DevOps usando linguagem natural.

Exemplo: Você pede ao Copilot _"crie um work item de bug no projeto X com prioridade alta"_ e ele usa este servidor para executar a ação diretamente no Azure DevOps.

Este projeto é um fork do Azure DevOps MCP Server da Microsoft, com suporte adicional a transporte HTTP/SSE remoto, autenticação OBO multi-usuário e deploy em containers.

📖 Índice

• Quick Start — Funcionando em 2 minutos
• Configuração nos Clientes MCP
• O que este servidor pode fazer
• Autenticação — Qual método usar?
• Opções da CLI
• Deploy em Produção (Azure Container Apps)
• Desenvolvimento Local
• Documentação Complementar
• Referências

⚡ Quick Start — Funcionando em 2 minutos

Pré-requisitos

• 20+ instalado
• Uma organização Azure DevOps existente
• Um Personal Access Token (PAT) do Azure DevOps

Passo 1 — Definir o token

Crie um PAT no Azure DevOps com as permissões necessárias (Read/Write nos escopos que você quer usar) e exporte como variável de ambiente:

# Linux/Mac
export ADO_MCP_AUTH_TOKEN="seu-pat-token-aqui"

# Windows (PowerShell)
$env:ADO_MCP_AUTH_TOKEN = "seu-pat-token-aqui"

Passo 2 — Clonar, instalar e buildar

git clone https://github.com/fsaito-github/azure-devops-mcp-remote.git
cd azure-devops-mcp-remote
npm install
npm run build

Passo 3 — Testar o servidor

Substitua sua-organizacao pelo nome da sua org no Azure DevOps (a parte que aparece em https://dev.azure.com/sua-organizacao):

node dist/index.js sua-organizacao --authentication envvar

Se não houver erros, o servidor está pronto. Encerre com Ctrl+C.

Passo 4 — Configurar no VS Code

Crie o arquivo .vscode/mcp.json no seu projeto (não no repo do MCP, mas no projeto onde você usa o Copilot):

{
  "servers": {
    "azure-devops": {
      "type": "stdio",
      "command": "node",
      "args": [
        "C:/caminho/completo/para/azure-devops-mcp-remote/dist/index.js",
        "sua-organizacao",
        "--authentication",
        "envvar"
      ]
    }
  }
}

⚠️ Importante: Substitua C:/caminho/completo/para/azure-devops-mcp-remote pelo caminho real onde você clonou o repositório. No Windows, use / ou \\\\ como separador.

Pronto! Abra o Copilot Chat no VS Code e peça algo como _"liste os work items do projeto MyProject"_.

💡 Para outros clientes (Claude Desktop, Cursor, etc.), veja a seção Configuração nos Clientes MCP.

🔌 Configuração nos Clientes MCP

VS Code / GitHub Copilot (stdio — local)

Crie .vscode/mcp.json na raiz do seu projeto:

{
  "servers": {
    "azure-devops": {
      "type": "stdio",
      "command": "node",
      "args": [
        "C:/caminho/para/azure-devops-mcp-remote/dist/index.js",
        "sua-organizacao",
        "--authentication",
        "envvar"
      ]
    }
  }
}

VS Code / GitHub Copilot (HTTP — servidor remoto)

Se o servidor está rodando remotamente (ex: Azure Container Apps):

{
  "servers": {
    "azure-devops": {
      "type": "http",
      "url": "https://seu-servidor.azurecontainerapps.io/mcp"
    }
  }
}

Se usando autenticação OBO, adicione o header com o JWT obtido via /auth/login:

{
  "servers": {
    "azure-devops": {
      "type": "http",
      "url": "https://seu-servidor.azurecontainerapps.io/mcp",
      "headers": {
        "Authorization": "Bearer seu-jwt-token-aqui"
      }
    }
  }
}

Claude Desktop

Em claude_desktop_config.json:

{
  "mcpServers": {
    "azure-devops": {
      "command": "node",
      "args": [
        "C:/caminho/para/azure-devops-mcp-remote/dist/index.js",
        "sua-organizacao",
        "--authentication",
        "envvar"
      ]
    }
  }
}

Cursor

Crie .cursor/mcp.json na raiz do projeto:

{
  "mcpServers": {
    "azure-devops": {
      "command": "node",
      "args": [
        "C:/caminho/para/azure-devops-mcp-remote/dist/index.js",
        "sua-organizacao",
        "--authentication",
        "envvar"
      ]
    }
  }
}

Visual Studio 2022

Crie .mcp.json na raiz da solução:

{
  "servers": {
    "azure-devops": {
      "type": "stdio",
      "command": "node",
      "args": [
        "C:/caminho/para/azure-devops-mcp-remote/dist/index.js",
        "sua-organizacao",
        "--authentication",
        "envvar"
      ]
    }
  }
}

Copilot Studio (servidor remoto)

1. No Power Platform, crie um Custom Connector apontando para https://seu-servidor/mcp
2. No Copilot Studio, adicione o connector como Tool (tipo MCP)
3. Se usando OBO, configure o header Authorization com o JWT do usuário

Transporte SSE (clientes mais antigos)

Se o seu cliente MCP só suporta SSE (e não Streamable HTTP):

{
  "servers": {
    "azure-devops": {
      "type": "sse",
      "url": "https://seu-servidor/sse"
    }
  }
}

O servidor precisa estar rodando com --transport sse neste caso.

🛠️ O que este servidor pode fazer

O servidor expõe 80+ operações organizadas em 9 domínios. Você pode habilitar apenas os domínios que precisa com a flag --domains.

Work Items (work-items)

Criar, ler, atualizar, comentar e vincular work items (bugs, tasks, user stories, etc.).

Repositórios Git (repositories)

Gerenciar repos, branches, PRs e code reviews.

Pipelines (pipelines)

Gerenciar builds, pipelines e artefatos.

Projetos e Times (core)

Iterações e Capacidade (work)

Wiki (wiki)

Test Plans (test-plans)

Busca (search)

Segurança Avançada (advanced-security)

Filtrando domínios

Se você só precisa de work items e repositórios, por exemplo:

npx -y @azure-devops/mcp sua-org -a envvar --domains repositories,work-items

Domínios disponíveis: core, repositories, pipelines, work-items, work, wiki, test-plans, search, advanced-security

🔐 Autenticação — Qual método usar?

Você está rodando local no seu computador?
├── SIM → Tem navegador disponível?
│   ├── SIM → Use "interactive" (padrão, abre o browser para login)
│   └── NÃO → Use "envvar" (PAT token via variável de ambiente)
│
└── NÃO → Está rodando em servidor/container remoto?
    ├── É Azure Container Apps / Azure VM?
    │   ├── Um único serviço (CI/CD, bot) → Use "env" (Managed Identity)
    │   └── Múltiplos usuários reais → Use "obo" (cada um com sua identidade)
    │
    ├── É GitHub Codespaces? → Use "azcli" (detectado automaticamente)
    │
    └── Outro ambiente? → Use "envvar" (PAT token)

Resumo dos métodos

Detalhes de cada método

PAT Token (-a envvar) — O mais simples para começar

1. Acesse https://dev.azure.com/sua-org/_usersSettings/tokens
2. Clique em New Token
3. Dê um nome, selecione os escopos (Read/Write) e copie o token
4. Defina a variável de ambiente:

export ADO_MCP_AUTH_TOKEN="seu-token-aqui"

1. Inicie o servidor:

npx -y @azure-devops/mcp sua-org -a envvar

⚠️ Todos os acessos ao Azure DevOps são feitos com a identidade do dono do PAT. Não há distinção por usuário.

OAuth Interativo (-a interactive) — Padrão para desktop

Não precisa configurar nada. Ao iniciar o servidor, ele abre automaticamente o browser para login:

npx -y @azure-devops/mcp sua-org

O token é cacheado — nas próximas execuções, o login é silencioso.

Azure CLI (-a azcli) — Para quem já usa az login

az login
npx -y @azure-devops/mcp sua-org -a azcli

Detectado automaticamente em GitHub Codespaces.

Managed Identity (-a env) — Para Azure sem segredos

Funciona automaticamente em Azure Container Apps, VMs e outros serviços com System-Assigned ou User-Assigned Managed Identity.

node dist/index.js sua-org --transport http --port 3000 -a env

A identidade precisa ser adicionada como usuário no Azure DevOps (veja a seção de Deploy).

OBO — On-Behalf-Of (-a obo) — Para produção multi-usuário

Neste modo, cada usuário faz login com sua conta Azure AD e todas as ações no Azure DevOps são rastreadas com a identidade real do usuário.

Requer um App Registration no Azure AD. Veja o guia completo: Azure AD Setup

Variáveis de ambiente necessárias:

OAUTH_CLIENT_ID=id-do-app-registration
OAUTH_CLIENT_SECRET=secret-do-app
OAUTH_TENANT_ID=id-do-tenant-azure-ad
OAUTH_REDIRECT_URL=http://localhost:8080/auth/callback
JWT_SECRET=uma-chave-secreta-aleatoria

Fluxo do usuário:

1. Servidor inicia: node dist/index.js sua-org --transport http --port 8080 -a obo
2. Usuário acessa http://localhost:8080/auth/login no browser
3. Faz login com Azure AD → recebe um JWT
4. Configura o JWT no cliente MCP (header Authorization: Bearer )
5. Todas as ações no Azure DevOps são feitas com a identidade desse usuário

Endpoints de autenticação:

Guia completo: Autenticação OBO

⚙️ Opções da CLI

mcp-server-azuredevops  [opções]

Exemplos:

# Desenvolvimento local com PAT (mais simples)
npx -y @azure-devops/mcp contoso -a envvar

# Servidor HTTP remoto com Managed Identity
node dist/index.js contoso --transport http --port 3000 -a env

# Apenas domínios de repos e pipelines
npx -y @azure-devops/mcp contoso -a envvar --domains repositories,pipelines

# Multi-usuário com OBO
node dist/index.js contoso --transport http --port 8080 -a obo

🏗️ Arquitetura

┌─────────────────┐                     ┌──────────────────────────────┐
│  Cliente MCP     │       HTTPS         │  Azure Container Apps        │
│                  │ ◄─────────────────► │                              │
│  • VS Code       │   (ou stdio local)  │  ┌──────────────────────┐   │
│  • Copilot       │                     │  │  MCP Server          │   │
│  • Claude        │                     │  │  --transport http     │   │
│  • Cursor        │                     │  │  --port 3000          │   │
│                  │                     │  └──────────┬───────────┘   │
└─────────────────┘                     │             │               │
                                         │      Token (PAT,           │
                                         │      Managed Identity      │
                                         │      ou OBO)               │
                                         └─────────────┼───────────────┘
                                                       │
                                         ┌─────────────▼───────────────┐
                                         │  Azure DevOps REST API      │
                                         │  dev.azure.com/        │
                                         └─────────────────────────────┘

Transportes disponíveis:

🚀 Deploy em Produção (Azure Container Apps)

Pré-requisitos

• Azure CLI instalado e autenticado (az login)
• Assinatura Azure ativa
• (opcional, para build local)

Passo 1 — Definir variáveis

RESOURCE_GROUP="rg-mcp-server"
LOCATION="eastus2"
ACR_NAME="acrmcpserver"           # deve ser único globalmente
CONTAINER_APP_ENV="mcp-env"
CONTAINER_APP_NAME="ado-mcp-server"
ADO_ORG="sua-organizacao"         # nome da sua org no Azure DevOps
IMAGE_NAME="ado-mcp-server"

Passo 2 — Criar os recursos Azure

# Resource Group
az group create --name $RESOURCE_GROUP --location $LOCATION

# Azure Container Registry
az acr create --name $ACR_NAME --resource-group $RESOURCE_GROUP --sku Basic --admin-enabled true

# Container Apps Environment
az containerapp env create \
  --name $CONTAINER_APP_ENV \
  --resource-group $RESOURCE_GROUP \
  --location $LOCATION

Passo 3 — Build e push da imagem Docker

# Build e push direto no ACR (não precisa de Docker local)
az acr build --registry $ACR_NAME --image $IMAGE_NAME:latest .

Ou, se preferir build local:

docker build -t $ACR_NAME.azurecr.io/$IMAGE_NAME:latest .
az acr login --name $ACR_NAME
docker push $ACR_NAME.azurecr.io/$IMAGE_NAME:latest

Passo 4 — Criar o Container App com Managed Identity

az containerapp create \
  --name $CONTAINER_APP_NAME \
  --resource-group $RESOURCE_GROUP \
  --environment $CONTAINER_APP_ENV \
  --image "$ACR_NAME.azurecr.io/$IMAGE_NAME:latest" \
  --registry-server "$ACR_NAME.azurecr.io" \
  --registry-identity system \
  --target-port 3000 \
  --ingress external \
  --system-assigned \
  --command "node" "dist/index.js" "$ADO_ORG" "--transport" "http" "--port" "3000" "-a" "env" \
  --min-replicas 1 \
  --max-replicas 3

Passo 5 — Configurar permissões da Managed Identity

# Obter o Principal ID da Managed Identity
PRINCIPAL_ID=$(az containerapp show \
  --name $CONTAINER_APP_NAME \
  --resource-group $RESOURCE_GROUP \
  --query "identity.principalId" -o tsv)

echo "Principal ID: $PRINCIPAL_ID"

Agora, adicione essa identity como usuário no Azure DevOps:

1. Acesse https://dev.azure.com/{sua-org}/_settings/users
2. Clique em Add users
3. Adicione o Object ID (que é o Principal ID acima) como usuário
4. Atribua a licença Basic ou Stakeholder
5. Dê permissões nos projetos necessários (Contributor, Reader, etc.)

💡 Dica: Para automatizar via API, use o Azure DevOps REST API - User Entitlements.

Passo 6 — Obter a URL e testar

FQDN=$(az containerapp show \
  --name $CONTAINER_APP_NAME \
  --resource-group $RESOURCE_GROUP \
  --query "properties.configuration.ingress.fqdn" -o tsv)

echo "MCP Server URL: https://$FQDN/mcp"

Teste com uma requisição MCP de inicialização:

curl -X POST https://$FQDN/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Se receber uma resposta JSON com "result", o servidor está funcionando! 🎉

Usando PAT ao invés de Managed Identity

Se preferir usar PAT Token no container:

az containerapp update \
  --name $CONTAINER_APP_NAME \
  --resource-group $RESOURCE_GROUP \
  --set-env-vars "ADO_MCP_AUTH_TOKEN=secretref:ado-pat" \
  --command "node" "dist/index.js" "$ADO_ORG" "--transport" "http" "--port" "3000" "-a" "envvar"

Limpeza de recursos

az group delete --name $RESOURCE_GROUP --yes --no-wait

🧪 Desenvolvimento Local

# Clonar e instalar
git clone https://github.com/microsoft/azure-devops-mcp.git
cd azure-devops-mcp
npm install

# Build
npm run build

# Rodar com PAT
export ADO_MCP_AUTH_TOKEN="seu-pat"
node dist/index.js sua-org -a envvar

# Rodar com HTTP transport
node dist/index.js sua-org --transport http --port 3000 -a envvar

# Rodar com Docker
docker build -t ado-mcp-server .
docker run -p 3000:3000 -e ADO_MCP_AUTH_TOKEN=seu-pat \
  ado-mcp-server sua-org --transport http --port 3000 -a envvar

# Rodar testes
npm test

# Rodar linter
npm run eslint

Variáveis de ambiente

Copie .env.example para .env e ajuste:

cp .env.example .env

📚 Documentação Complementar

📝 Referências

• Azure DevOps MCP Server (original)
• MCP Specification — Transports
• Azure Container Apps — Docs
• DefaultAzureCredential
• Deploy MCP Server + Copilot Studio

📄 Licença