Setup

The eight read tools need a PAT with the Work Items read scope. The four write tools need one scope more.

1. Issue your PAT

The server uses your own personal access token, not an agency one, so every write is attributed to you in the work item’s history.

1. In Azure DevOps, open User settings → Personal access tokens → New Token.

2. Scope it to the organisation that holds the board.

3. Under Work Items, select Read & write — that’s the vso.work_write scope the write tools need. Read alone works for the eight read tools; the four write tools then refuse with a message naming the scope. (Read, write, & manage also works but grants more than this server uses.)

4. Set an expiry you’ll remember. Once it lapses the read tools return “rejected the PAT” and the write tools report the scope message instead — both surface as a 401, so a write can’t tell an expired PAT from a read-only one.

5. Export it in your shell, then reload:

   export DEVOPS_API_KEY="your-pat-here"

   source ~/.zshrc

Then restart your coding agent — MCP headers are read at startup.

The PAT never leaves your machine's control

devops-mcp holds no credential store of its own — no agency key, no database, no audit log. Your PAT is the Authorization: Bearer token on every request, is held in memory for the life of that request, and is never persisted. The server grants no access you don’t already have in Azure DevOps. Rotating the token is a ~/.zshrc edit and a restart, with nothing to update server-side.

2. Config entry

/setup writes this for you. Both x-devops-org and x-devops-project are required — the server is not scoped to one client and has no defaults:

"devops-mcp": {
  "type": "http",
  "url": "https://devops.mcp.dotcollective.com.au/mcp",
  "headers": {
    "Authorization": "Bearer ${DEVOPS_API_KEY}",
    "x-devops-org": "<your-azure-devops-org>",
    "x-devops-project": "<your-project>"
  }
}

The token goes in the Authorization header — the same shape as figma-mcp (Bearer ${FIGMA_API_KEY}) and productive-mcp (Bearer ${PRODUCTIVE_API_KEY}). There is no separate agency API key for this server.

Your board URL is https://dev.azure.com/<org>/<project>/_boards — the two path segments are the values you need.

| Header | Required | Notes | |---|---|---| | Authorization | Yes | Bearer + your Azure DevOps PAT | | x-devops-org | Yes | No default | | x-devops-project | Yes | No default | | x-devops-team | No | Defaults to <project> Team — set it only to target another team | | x-autonomous | No | true blocks all four write tools |

OpenCode uses {env:VAR} instead of ${VAR}; Antigravity uses serverUrl instead of type + url. See Server Stack.

Writes are blocked in autonomous sessions

With "x-autonomous": "true" in this server’s own headers block, all four write tools refuse. Reads keep working, so an unattended run can orient on a ticket but never mutate the client’s board. The header is read per-server — setting it on dev-mcp alone does not gate these tools, so it belongs here too on autonomous projects. /setup handles both entries.

3. Verify

Ask your agent to pull a work item you know exists. If it returns JSON with the title and state, the PAT, org and project are all correct. Anything else is covered in Troubleshooting.