ado-code-mode-mcp

Token-efficient Azure DevOps MCP server using the Code Mode pattern. Replaces 99 tools with 2 — reducing bootstrap context from ~98K tokens to ~1K.

Why

The official Microsoft Azure DevOps MCP server (@azure-devops/mcp) exposes 99 tools. Loading all tool schemas costs ~89,000-98,000 tokens before any useful reasoning begins. Most sessions use 5-10 tools.

This server exposes 2 tools:

• ado_search — discover available operations by keyword
• ado_execute — run JavaScript code against a sandboxed ado proxy object

The model writes code that calls ado.workItems.get(123) instead of invoking individual tools. Results are projected (only requested fields returned), saving 50-75% of response tokens too.

Install

One-liner for Claude Code:

claude mcp add ado -- npx -y ado-code-mode-mcp --org myorg

Replace myorg with your Azure DevOps organization (the part before .visualstudio.com or after dev.azure.com/).

For PAT authentication, set the env var first:

export AZURE_DEVOPS_PAT=your-pat-here
claude mcp add ado -- npx -y ado-code-mode-mcp --org myorg

For comparison, the official Microsoft ADO MCP server installs with:

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

That loads 99 tools (~98K tokens). This server loads 2 tools (~1K tokens).

Alternative: .mcp.json configuration

{
  "mcpServers": {
    "ado": {
      "command": "npx",
      "args": ["-y", "ado-code-mode-mcp", "--org", "myorg"],
      "env": {
        "AZURE_DEVOPS_PAT": "your-pat-here"
      }
    }
  }
}

Standalone

# With PAT authentication
AZURE_DEVOPS_ORG=myorg AZURE_DEVOPS_PAT=xxxx npx ado-code-mode-mcp

# With Azure CLI authentication (requires 'az login' first)
AZURE_DEVOPS_ORG=myorg npx ado-code-mode-mcp

Usage

Search for operations

ado_search({ query: "current sprint work items" })

Returns matching operations with signatures and examples:

Found 3 operations:

1. work.listTeamIterations [read-only]
   await ado.work.listTeamIterations({ project: "MyProj", team: "MyTeam", timeframe: "current" })
   → Iteration[] — List iterations/sprints for a team

2. work.getWorkItemsForIteration [read-only]
   await ado.work.getWorkItemsForIteration({ project: "MyProj", team: "MyTeam", iterationId: "abc" })
   → WorkItemRef[] — Get work item IDs for a sprint

Execute operations

ado_execute({
  code: `
    const iters = await ado.work.listTeamIterations({ project: "MyProj", team: "MyTeam", timeframe: "current" });
    const items = await ado.work.getWorkItemsForIteration({ project: "MyProj", team: "MyTeam", iterationId: iters[0].id });
    const details = await ado.workItems.getBatch(items.map(i => i.id));
    result = details.map(d => ({
      id: d.id,
      title: d.fields["System.Title"],
      state: d.fields["System.State"],
      assigned: d.fields["System.AssignedTo"]?.displayName
    }));
  `,
  project: "MyProj",
  team: "MyTeam"
})

Returns only the projected fields — not the full ADO API response.

Token Budget

| Component | Microsoft's Server (99 tools) | This Server (2 tools) | |-----------|------------------------------|----------------------| | Bootstrap | ~89,000-98,000 tokens | ~1,000 tokens | | Sprint review flow | ~3,900 tokens in responses | ~200 tokens (projected) | | 5-operation session | ~92,000-108,000 tokens | ~2,500-4,000 tokens | | Savings | — | ~95-97% |

Available Domains

| Domain | Operations | Proxy | |--------|-----------|-------| | Work Items | get, getBatch, create, update, query, comment, link, ... | ado.workItems.* | | Work | iterations, capacity, team settings, boards | ado.work.* | | Repositories | repos, PRs, branches, commits, diffs, threads | ado.repos.* | | Pipelines | builds, runs, definitions, logs, artifacts | ado.pipelines.* | | Core | projects, teams | ado.core.* | | Wiki | pages, content | ado.wiki.* | | Search | code, work items, wiki | ado.search.* | | Test Plans | plans, suites, cases, results | ado.testPlans.* | | Security | alerts | ado.security.* |

Authentication

Two mechanisms (see ADR-003):

1. PAT — set AZURE_DEVOPS_PAT environment variable with your Personal Access Token
2. Azure CLI — run az login first, then the server uses your Azure CLI session

Auto-detection: PAT takes precedence if set, otherwise Azure CLI.

Architecture

See the Architecture Decision Records:

• ADR-001: Code Mode over native tools
• ADR-002: node:vm sandbox
• ADR-003: PAT + Azure CLI auth

Development

npm install
npm test        # run unit tests
npm run build   # compile TypeScript
npm run dev     # run with tsx (dev mode)

License

MIT