ado-mcp

README

Azure DevOps MCP Server (ado-mcp)

An Azure DevOps Model Context Protocol (MCP) server, written in Go, that exposes the Azure DevOps REST API (plus 7pace Timetracker) as tools an LLM client (Claude Desktop/Code, Cursor, and others) can call. See the Documentation for more details.

In this README, roughly shallow to deep: Install → Features → Configuration → CLI → Toolsets → Tools → Prompts → Architecture → Development → Changelog. The docs site mirrors this same path as separate pages, if you'd rather not scroll.

Install

Prebuilt binaries are published on the latest release. Download the archive for your platform, extract the ado binary, and put it on your PATH:

Platform	Architecture	Download (latest)
macOS	Apple Silicon (arm64)	ado-mcp_darwin_arm64.tar.gz
macOS	Intel (amd64)	ado-mcp_darwin_amd64.tar.gz
Linux	amd64	ado-mcp_linux_amd64.tar.gz
Linux	arm64	ado-mcp_linux_arm64.tar.gz
Windows	amd64	ado-mcp_windows_amd64.zip
Windows	arm64	ado-mcp_windows_arm64.zip

Each link always resolves to the newest release. A checksums.txt is published alongside the archives.

macOS / Linux

Pick your OS/ARCH:

OS=darwin ARCH=arm64   # OS: darwin|linux   ARCH: amd64|arm64
curl -sSL "https://github.com/rangertaha/ado-mcp/releases/latest/download/ado-mcp_${OS}_${ARCH}.tar.gz" | tar -xz ado
sudo mv ado /usr/local/bin/
ado --version

Windows (PowerShell)

Pick your $Arch:

$Arch = "amd64"   # ARCH: amd64|arm64
Invoke-WebRequest "https://github.com/rangertaha/ado-mcp/releases/latest/download/ado-mcp_windows_${Arch}.zip" -OutFile ado.zip
Expand-Archive ado.zip -DestinationPath .
.\ado.exe --version

Install with Go

go install github.com/rangertaha/ado-mcp/cmd/ado@latest

Build from source

git clone https://github.com/rangertaha/ado-mcp
cd ado-mcp
make build        # produces ./bin/ado

Broad coverage of Azure DevOps: 274 tools across 34 toolsets plus 7 workflow prompts (surfaced as slash commands by MCP clients), spanning projects, work items, Git/pull requests, pipelines, releases, test plans, boards, artifacts, wiki, graph/identity, security, service hooks, dashboards, audit, distributed task (variable groups/environments/agent pools/deployment groups), service connections, branch policies, code/work-item/wiki search, process customization, member entitlement, notifications, extensions, TFVC, advanced security alerts, approvals & checks, identities, operations, profile, composite macros, statistics/surveys, favorites, delivery plans, a local notes store, and 7pace time tracking.

A built-in workflow: keep engineering notes (stored locally in SQLite under your config directory) tagged by project/env/service/version/repo/branch/users, with a real time range, free-text search, and discoverable dimension values. Notes can optionally sync with 7pace (push a note's date/start/stop/summary as a worklog, or pull worklogs in as notes). See the notes toolset and the new_note prompt.

Features

• Azure DevOps, 7pace, and local notes: the Azure DevOps REST API and 7pace Timetracker exposed as tools, plus an optional local notes store stored in SQLite (experimental).
• Typed tools with schemas: every tool has an auto-generated JSON Schema for its input and output, inferred from Go structs, with per-field descriptions. Inputs are validated before a handler runs.
• Read-only switch: ADO_READONLY=true hides every mutating tool, so the server can be safely pointed at production.
• Toolset filtering: enable only the areas you need with ADO_TOOLSETS to keep the tool list focused.
• Multi-host aware: transparently routes to the Azure DevOps service hosts (dev.azure.com, vssps, vsrm, feeds, auditservice, almsearch, vsaex, extmgmt, advsec).
• Built on the official SDK: uses modelcontextprotocol/go-sdk (v1).
• Response caching: GET responses are cached in memory for a short TTL (ADO_CACHE_TTL, default 30s) and any write instantly invalidates the cache, so repeated reads within a task are fast without risking stale data after a mutation.

Configuration

All configuration is read from the environment.

Variable	Required	Description
ADO_ORG_URL	yes	Organization URL, e.g. https://dev.azure.com/myorg.
ADO_PAT	yes	Azure DevOps Personal Access Token. Sent via Basic auth.
SEVENPACE_ORG	no	7pace account name; builds https://{org}.timehub.7pace.com/api/odata/{version}.
SEVENPACE_API_BASE	no	Full 7pace API base URL; overrides the URL derived from SEVENPACE_ORG.
SEVENPACE_TOKEN	no	7pace bearer token (Settings → Reporting and API). Enables 7pace tools.
ADO_TOOLSETS	no	Comma-separated toolset names to enable, or all (default).
ADO_READONLY	no	Truthy (1, true, yes, on) to expose only read-only tools.
ADO_MCP_HOME	no	Override the app directory (default: <user config dir>/ado-mcp, e.g. ~/.config/ado-mcp). The notes SQLite database lives in data/ within it.
SEVENPACE_REST_BASE	no	Full 7pace write-capable REST API base URL; overrides the URL derived from SEVENPACE_ORG (default https://{org}.timehub.7pace.com/api/rest). Only used by sevenpace_create_worklog and notes_push_sevenpace.
ADO_CACHE_TTL	no	How long GET responses are cached in memory, e.g. 1m. 0 or off disables caching. Default: 30s. Any write clears the cache immediately.

7pace is optional: its tools register only when SEVENPACE_TOKEN is set together with either SEVENPACE_ORG or SEVENPACE_API_BASE.

Use with Claude Desktop / Claude Code

Add to your MCP client configuration (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "ado": {
      "command": "ado",
      "args": ["mcp"],
      "env": {
        "ADO_ORG_URL": "https://dev.azure.com/myorg",
        "ADO_PAT": "your-pat",
        "SEVENPACE_ORG": "myorg",
        "SEVENPACE_TOKEN": "your-7pace-token"
      }
    }
  }
}

For Claude Code: claude mcp add ado --env ADO_ORG_URL=... --env ADO_PAT=... -- ado mcp.

Local development

The repo ships a committed .mcp.json that runs the server straight from source (go run ./cmd/ado mcp), so changes take effect on the next session without a build step. It reads credentials from your environment (no secrets in the repo). Run cp .env.example .env and fill it in, or export ADO_ORG_URL and ADO_PAT (and optionally SEVENPACE_ORG/SEVENPACE_TOKEN) before launching Claude Code in this directory. A local .claude/settings.local.json auto-trusts the server via "enableAllProjectMcpServers": true.

CLI

The ado command tree (mcp, test, note)

ado is a small command tree (built on urfave/cli):

• ado mcp: run the MCP server over stdio. This is what MCP clients (Claude Desktop/Code, Cursor) invoke.
• ado test: verify connectivity and credentials against Azure DevOps (calls the profile endpoint and prints the authenticated user).
• ado note: manage the local SQLite notes store. These commands do not require Azure DevOps credentials.
  • ado note add "<summary>" [--date YYYY-MM-DD] [--start RFC3339] [--stop RFC3339] [--body TEXT] [--project|-p NAME] [--env NAME] [--service NAME] [--version V] [--repo NAME] [--branch NAME] [--users CSV]: add a note (summary is positional).
  • ado note list [--date] [--from] [--to] [--project] [--env] [--service] [--version] [--repo] [--branch] [--user] [--search] [--limit N]: list notes, newest first.
  • ado note update <id> [--summary|-s] [--date] [--start] [--stop] [--body] [--project] [--env] [--service] [--version] [--repo] [--branch] [--users]: update fields.
  • ado note delete <id> (alias rm): delete a note.

Toolsets

All 34 toolsets

Pass any subset to ADO_TOOLSETS (e.g. ADO_TOOLSETS=core,wit,git). 7pace uses the toolset name sevenpace. An unrecognized name fails startup with an error listing the valid names, rather than silently registering fewer tools than expected.

Toolset	Host	Covers
core	dev.azure.com	projects (CRUD), teams, team members, team settings/field values/iterations, processes
wit	dev.azure.com	work items (CRUD, batch update), WIQL, comments, types, fields, tags, attachments, revisions, recycle bin
git	dev.azure.com	repos (create/delete/import), branches, commits, file commits, PRs (+ iterations/diffs), threads, reviewers, votes, statuses, annotated tags, pushes
pipelines	dev.azure.com	pipelines, runs, builds, logs, definitions (CRUD), tags, artifacts
release	vsrm	release definitions (CRUD), releases, deployments, approvals
test	dev.azure.com	test plans, suites, cases, runs, results, points, configurations
boards	dev.azure.com	backlogs, iterations, capacity, boards, columns
artifacts	feeds	feeds, packages, package versions
wiki	dev.azure.com	wikis (CRUD/rename), pages (CRUD, append, list-tree, by-id, stats), attachments, moves
graph	vssps	users, groups, memberships
security	dev.azure.com	security namespaces, access control lists
servicehooks	dev.azure.com	subscriptions (CRUD)
dashboards	dev.azure.com	dashboards, widgets
audit	auditservice	audit log query
distributedtask	dev.azure.com	variable groups, environments, agent pools, secure files, deployment groups
serviceendpoint	dev.azure.com	service connections (endpoints, CRUD) and types
policy	dev.azure.com	branch/repo policy configurations (CRUD), types, PR evaluations
search	almsearch	code, work item, and wiki full-text search (multi-value scoping, sort, facets)
processes	dev.azure.com	process customization (CRUD): work item types, fields, states, behaviors
memberentitlement	vsaex	user/group entitlements (licensing)
notification	dev.azure.com	notification subscriptions (CRUD) and event types
extension	extmgmt	installed extensions (list, install/uninstall/enable/disable)
tfvc	dev.azure.com	TFVC changesets, branches, items
advsec	advsec	Advanced Security code-scanning alerts
approvals	dev.azure.com	pipeline run approvals and checks (configurations CRUD)
identities	vssps	legacy identity lookup
operations	dev.azure.com	async operation status
profile	vssps	the authenticated user's profile
macros	dev.azure.com	composite tools: complete PR, create bug, publish wiki page (+images)
stats	dev.azure.com	surveys: contributors (repo/project/org), PR/work-item/build stats
favorites	dev.azure.com	list/create/delete the caller's favorites (queries, dashboards, etc.)
deliveryplans	dev.azure.com	list delivery plans and get a plan's metadata
notes	local (SQLite)	engineering notes (project/env/service/version/repo/branch/users, time range): add/list/get/update/delete/summary, distinct-value listing, key/value config, optional 7pace push/pull
sevenpace	timehub.7pace	worklogs, worklog↔work-item joins, work-item time rollups, budgets, raw OData query, plus a best-effort write endpoint for new worklogs

Tools

Tools follow the naming convention <toolset>_<verb>_<noun>. Tools marked [write] mutate data and are hidden when ADO_READONLY=true.

All 274 tools

core

• core_add_team_iteration [write]: Assign an existing classification node (iteration) to a team. iterationID is the classification node's GUID, obtainable via wit_list_classification_nodes.
• core_create_project [write]: Create a new team project. This is a long-running operation: the response is the raw operation reference; poll it with the operations_get tool to know when the project is ready.
• core_delete_project [write]: Delete a project by ID. This is a long-running operation: the response is the raw operation reference; poll it with the operations_get tool to know when the deletion completes.
• core_get_project: Get a single Azure DevOps project by name or ID.
• core_get_team: Get a single team within a project by name or ID.
• core_get_team_field_values: Get a team's area-path field values: the default area path and included sub-paths.
• core_get_team_settings: Get a team's settings: backlog visibilities, bugs behavior, working days, default iteration, etc.
• core_list_processes: List the process templates (e.g. Agile, Scrum, CMMI) available to the organization.
• core_list_projects: List the team projects in the Azure DevOps organization, optionally filtered by state (e.g. wellFormed) and paged with top/skip.
• core_list_team_members: List the members of a team within a project, paged with top/skip.
• core_list_teams: List the teams within a project, optionally restricted to teams the caller is a member of, and paged with top/skip.
• core_remove_team_iteration [write]: Unassign an iteration from a team.
• core_update_project [write]: Update an existing project (e.g. rename, change description or visibility) from a raw body. This is a long-running operation: the response is the raw operation reference; poll it with the operations_get tool to know when the update completes.
• core_update_team_field_values [write]: Update a team's area-path field values from a raw body, e.g. {"defaultValue": "...", "values": [{"value": "...", "includeChildren": true}]}.
• core_update_team_settings [write]: Update a team's settings from a raw body.

wit

• wit_add_comment [write]: Add a comment to a work item.
• wit_add_relation [write]: Add a relation (link or attachment) to a work item. rel is the relation type, e.g. "System.LinkTypes.Related" or "AttachedFile".
• wit_batch_update [write]: Update fields on multiple work items in a single request. Provide a list of items, each with an id and fields keyed by reference name to set.
• wit_create_attachment [write]: Upload an attachment and get a reference URL. Content must be base64-encoded; it is decoded before upload. Then call wit_add_relation with rel="AttachedFile" and the returned url to attach it to a work item.
• wit_create_work_item [write]: Create a work item of a given type. Provide fields keyed by reference name, e.g. {"System.Title": "Fix bug", "System.Description": "..."}.
• wit_delete_tag [write]: Delete a work item tag by ID or name.
• wit_delete_work_item [write]: Delete a work item. By default it goes to the recycle bin; set destroy=true to permanently remove it.
• wit_get_deleted_work_item: Get a single deleted work item from a project's recycle bin by ID.
• wit_get_revision: Get a single specific revision of a work item.
• wit_get_work_item: Get a single work item by ID, including its fields.
• wit_get_work_items: Get multiple work items by ID in one request. Optionally restrict to specific fields.
• wit_list_classification_nodes: List the classification node tree for a project. structureGroup is "areas" or "iterations". Optionally expand to a given depth.
• wit_list_comments: List the comments on a work item. Returns a continuationToken to fetch the next page when more comments exist.
• wit_list_deleted_work_items: List the work items in a project's recycle bin.
• wit_list_fields: List the work item field definitions in the organization.
• wit_list_queries: List the saved queries and query folders in a project. Optionally expand to a given depth.
• wit_list_revisions: List all revisions of a work item, optionally paginated with top/skip.
• wit_list_tags: List the work item tags defined in a project.
• wit_list_work_item_types: List the work item types (e.g. Bug, User Story, Task) defined in a project.
• wit_query: Run a Work Item Query Language (WIQL) query and return matching work item IDs. Example: "SELECT [System.Id] FROM WorkItems WHERE [System.State] = 'Active'".
• wit_restore_work_item [write]: Restore a work item from a project's recycle bin.
• wit_update_work_item [write]: Update fields on an existing work item. Provide fields keyed by reference name, e.g. {"System.State": "Closed"}.

git

• git_add_pr_comment [write]: Add a new comment thread to a pull request.
• git_add_pr_reviewer [write]: Add (or update) a reviewer on a pull request, optionally marking them required.
• git_create_annotated_tag [write]: Create an annotated tag pointing at a target object (usually a commit SHA).
• git_create_branch [write]: Create a new branch pointing at a commit SHA.
• git_create_commit_status [write]: Post a status against a commit (state: succeeded, failed, pending, error, notApplicable).
• git_create_pull_request [write]: Create a pull request from a source branch into a target branch.
• git_create_repository [write]: Create a new Git repository in a project.
• git_delete_repository [write]: Delete a Git repository by its ID.
• git_get_annotated_tag: Get an annotated tag object by its object ID.
• git_get_commit_diffs: Compare two versions (branches, tags, or commits) in a repository and return the file-level diff.
• git_get_file: Get the text content of a file at a path, optionally at a specific branch.
• git_get_import_request: Get the status of a repository import request.
• git_get_pr_iteration_changes: Get the file changes for a single pull request iteration, optionally paged with top/skip.
• git_get_pull_request: Get a pull request by ID.
• git_get_repository: Get a Git repository by name or ID.
• git_import_repository [write]: Start an import of an external Git repository into an existing (typically empty) repository. Use serviceEndpointId to reference stored credentials for a private source.
• git_list_commit_statuses: List the statuses posted against a commit.
• git_list_commits: List commits in a repository, optionally on a specific branch, filtered by author or date range, restricted to a file/folder path, and paged with top/skip.
• git_list_pr_iterations: List the iterations (updates) of a pull request.
• git_list_pr_reviewers: List the reviewers on a pull request and their votes.
• git_list_pr_threads: List the comment threads on a pull request.
• git_list_pull_requests: List pull requests in a repository, filtered by status (active, completed, abandoned, all), and optionally by creator or reviewer identity ID.
• git_list_pushes: List the push history for a repository, optionally paged with top/skip and filtered to a pusher's identity ID.
• git_list_refs: List refs in a repository. Use filter "heads/" for branches or "tags/" for tags. Optionally include commit statuses (and limit to the latest per pipeline) or peel annotated tags to their target commit. Returns a continuationToken to fetch the next page when more refs exist.
• git_list_repositories: List the Git repositories in a project.
• git_push_file [write]: Add, edit, or delete a single file on a branch in one commit (push). changeType is add, edit, or delete; the branch tip is resolved automatically.
• git_remove_pr_reviewer [write]: Remove a reviewer from a pull request.
• git_update_pull_request [write]: Update a pull request: set status to completed or abandoned, or change title/description.
• git_vote_pull_request [write]: Set a reviewer's vote on a pull request (10 approve, 5 approve with suggestions, 0 reset, -5 waiting, -10 reject).

pipelines

• pipelines_add_build_tag [write]: Add a tag to a build.
• pipelines_cancel_build [write]: Request cancellation of an in-progress build.
• pipelines_create_definition [write]: Create a build definition within a project from a raw definition body.
• pipelines_delete_definition [write]: Delete a build definition by ID.
• pipelines_get: Get a pipeline by ID.
• pipelines_get_build: Get a single build by ID.
• pipelines_get_build_changes: Get the source changes associated with a build.
• pipelines_get_build_log: Get the text of a specific build log.
• pipelines_get_build_timeline: Get the execution timeline of a build.
• pipelines_get_definition: Get a single build definition by ID, as a raw object (definitions have a large, variable schema).
• pipelines_get_run: Get a single pipeline run by ID.
• pipelines_list: List the pipelines in a project. Returns a continuationToken to fetch the next page when more pipelines exist.
• pipelines_list_artifacts: List the artifacts produced by a build.
• pipelines_list_build_logs: List the logs produced by a build.
• pipelines_list_build_tags: List the tags on a build.
• pipelines_list_builds: List builds in a project, optionally filtered by build definition, requester identity, time range, status, result, reason, branch, or query order. Returns a continuationToken to fetch the next page when more builds exist.
• pipelines_list_definitions: List the build definitions in a project, optionally filtered by name (supports wildcards) or folder path. Returns a continuationToken to fetch the next page when more definitions exist.
• pipelines_list_runs: List the runs of a pipeline.
• pipelines_remove_build_tag [write]: Remove a tag from a build.
• pipelines_run [write]: Queue a new run of a pipeline, optionally on a specific branch.
• pipelines_update_definition [write]: Update an existing build definition from a raw definition body.

release

• release_create_definition [write]: Create a release definition in a project from a raw body.
• release_create_release [write]: Create a new release from a release definition.
• release_delete_definition [write]: Delete a release definition by ID.
• release_deploy_environment [write]: Start a deployment of a release to an environment.
• release_get_definition: Get a single release definition by ID.
• release_get_release: Get a single release by ID.
• release_list_approvals: List release approvals in a project, optionally filtered by status or assignee.
• release_list_definitions: List the release definitions in a project. Returns a continuationToken to fetch the next page when more definitions exist.
• release_list_deployments: List deployments in a project, optionally filtered by release definition, creator, started-time range, deployment status, operation status, or source branch. Returns a continuationToken to fetch the next page when more deployments exist.
• release_list_manual_interventions: List the manual interventions for a release.
• release_list_releases: List releases in a project, optionally filtered by release definition, creator, created-time range, status, environment status, source branch, search text, tag, or query order. Returns a continuationToken to fetch the next page when more releases exist.
• release_update_approval [write]: Approve or reject a release approval.
• release_update_definition [write]: Update an existing release definition. Azure DevOps updates release definitions via PUT to the definitions collection, not a per-ID route: the body must be the full definition object, including its current id and revision. GET the definition first (release_get_definition), modify the returned object, and pass it back whole.
• release_update_manual_intervention [write]: Approve or reject a manual intervention in a release.

test

• test_add_results [write]: Add test results to a test run.
• test_add_suite_cases [write]: Add existing test case work items to a test suite.
• test_create_configuration [write]: Create a test configuration.
• test_create_run [write]: Create a new manual test run for a test plan.
• test_delete_configuration [write]: Delete a test configuration.
• test_get_configuration: Get a single test configuration by ID.
• test_get_plan: Get a single test plan by ID.
• test_get_run: Get a single test run by ID.
• test_list_cases: List the test cases in a test suite. Returns a continuationToken to fetch the next page when more test cases exist.
• test_list_configurations: List the test configurations in a project. Returns a continuationToken to fetch the next page when more configurations exist.
• test_list_plans: List the test plans in a project.
• test_list_points: List the test points (one per test case + configuration combination) in a suite.
• test_list_results: List the results for a test run, with paging via top/skip and optional details to include (e.g. Iterations, WorkItems).
• test_list_runs: List the test runs in a project, optionally restricted to a test plan and filtered by automated status, with paging via top/skip (the API caps at 100 results per call).
• test_list_suites: List the test suites in a test plan. Returns a continuationToken to fetch the next page when more suites exist.
• test_remove_suite_cases [write]: Remove test cases from a test suite.
• test_update_configuration [write]: Update a test configuration.
• test_update_points [write]: Update the outcome of one or more test points (e.g. mark as Passed, Failed, Blocked).
• test_update_run [write]: Update the state of a test run (e.g. InProgress, Completed, Aborted).

boards

• boards_get_board_columns: Get the columns configured on a board.
• boards_get_board_rows: Get the rows (swimlanes) configured on a board.
• boards_get_iteration_capacity: Get the team capacity for a specific iteration.
• boards_list_backlog_work_items: List the work items contained in a backlog level.
• boards_list_backlogs: List the backlog levels configured for a team.
• boards_list_board_charts: List the charts available for a board.
• boards_list_boards: List the boards available to a team.
• boards_list_iterations: List the iterations (sprints) assigned to a team, optionally filtered by timeframe. Only "current" is actually honored by Azure DevOps today; other values are accepted but have no filtering effect.

artifacts

• artifacts_get_feed: Get a single packaging feed by its ID or name.
• artifacts_get_package: Get a single package within a feed by its ID.
• artifacts_list_feed_views: List the views defined on a packaging feed.
• artifacts_list_feeds: List the Azure Artifacts packaging feeds available to the caller.
• artifacts_list_package_versions: List the published versions of a package in a feed.
• artifacts_list_packages: List the packages contained in a feed, optionally filtered by name or protocol type, including all versions and/or deleted packages, and paged with top/skip.

wiki

• wiki_append_to_page [write]: Append content to an existing wiki page (creating it if absent) without resending the whole page. Useful for adding changelog entries, notes, or sections.
• wiki_create_attachment [write]: Upload an attachment to a wiki. Content must be base64-encoded; it is decoded before upload.
• wiki_create_or_update_page [write]: Create a new wiki page or update an existing one at the given path. Automatically fetches the current page's ETag and sends it as If-Match when updating, so it works reliably for both creating new pages and editing existing ones.
• wiki_create_wiki [write]: Create a new project or code wiki in a project. type must be 'projectWiki' or 'codeWiki'.
• wiki_delete_page [write]: Delete a wiki page at the given path.
• wiki_delete_wiki [write]: Delete (unpublish) a wiki by ID or name.
• wiki_get_page: Get a wiki page by path, optionally including its content and (with recursionLevel='full') its subpages.
• wiki_get_page_by_id: Get a wiki page by its numeric page ID, optionally including content.
• wiki_get_page_stats: Get view statistics for a wiki page over the last N days.
• wiki_get_wiki: Get a single wiki by ID or name.
• wiki_list_pages: List the page tree of a wiki (expanded to full depth) from a root path, for browsing structure.
• wiki_list_wikis: List the wikis in a project.
• wiki_move_page [write]: Move or rename a wiki page from one path to another.
• wiki_update_wiki [write]: Rename a wiki.

graph

• graph_add_membership [write]: Create a membership relating a subject to a container.
• graph_get_descriptor: Resolve a storage key (subject id) to its graph descriptor.
• graph_list_groups: List the group subjects in the organization graph, optionally filtered by subject types (e.g. aad,vsts) and paged with a continuation token.
• graph_list_memberships: List the memberships of a subject (optionally up to containers or down to members).
• graph_list_users: List the user subjects in the organization graph, optionally filtered by subject types (e.g. aad,vsts) and paged with a continuation token.
• graph_remove_membership [write]: Remove a membership relating a subject to a container.

security

• security_list_access_control_lists: List the access control lists for a security namespace, optionally filtered by token or a comma-separated list of identity descriptors, optionally recursing through child tokens.
• security_list_namespaces: List the security namespaces in the organization, optionally filtered by namespace ID.
• security_remove_access_control_lists [write]: Remove the access control lists for the given tokens in a security namespace, optionally also removing child ACLs of those tokens (recurse).
• security_set_access_control_entries [write]: Add or update access control entries on the ACL for a token in a security namespace.

servicehooks

• servicehooks_create_subscription [write]: Create a new service hook subscription.
• servicehooks_delete_subscription [write]: Delete a service hook subscription by ID.
• servicehooks_get_subscription: Get a single service hook subscription by ID.
• servicehooks_list_consumers: List the available service hook consumers in the organization.
• servicehooks_list_publishers: List the available service hook publishers in the organization.
• servicehooks_list_subscriptions: List the service hook subscriptions in the organization, optionally filtered by publisher, event type, consumer, or consumer action.

dashboards

• dashboards_create_dashboard [write]: Create a new dashboard for a team within a project.
• dashboards_delete_dashboard [write]: Delete a dashboard by its ID for a team within a project.
• dashboards_get_dashboard: Get a single dashboard by its ID.
• dashboards_list_dashboards: List the dashboards for a team within a project.
• dashboards_list_widgets: List the widgets on a dashboard.

audit

• audit_query_log: Query the organization-level Azure DevOps audit log. Returns a single page of decorated audit log entries; more pages may exist. Pass continuationToken to page past the first batch.

dtask

• dtask_create_deployment_group [write]: Create a deployment group within a project.
• dtask_create_environment [write]: Create a deployment environment within a project.
• dtask_create_variable_group [write]: Create a variable group within a project from a raw body.
• dtask_delete_deployment_group [write]: Delete a deployment group by its ID.
• dtask_get_deployment_group: Get a single deployment group by its ID, optionally including its target machines.
• dtask_get_environment: Get a single deployment environment by its ID.
• dtask_get_variable_group: Get a single variable group by its ID.
• dtask_list_agent_pools: List the organization-level agent pools, optionally filtered by pool name and/or pool type (e.g. "automation" or "deployment").
• dtask_list_deployment_group_targets: List the target machines registered in a deployment group. Returns a continuationToken to fetch the next page when more targets exist.
• dtask_list_deployment_groups: List the deployment groups within a project, optionally filtered by name. Returns a continuationToken to fetch the next page when more deployment groups exist.
• dtask_list_environments: List the deployment environments within a project. Returns a continuationToken to fetch the next page when more environments exist.
• dtask_list_secure_files: List the secure files within a project, optionally filtered by a name pattern (supports wildcards).
• dtask_list_variable_groups: List the variable groups within a project, optionally filtered by group name and/or action filter (e.g. "manage").

serviceendpoint

• serviceendpoint_create [write]: Create a service endpoint (service connection) from a raw body (name, type, url, authorization, etc., per Azure DevOps' documented schema), which must include serviceEndpointProjectReferences to scope it to one or more projects.
• serviceendpoint_delete [write]: Delete a service endpoint, removing it from the projects identified by a comma-separated list of project IDs.
• serviceendpoint_get: Get a single service endpoint by ID within a project.
• serviceendpoint_list: List the service endpoints (service connections) in a project, optionally filtered by type or authorization scheme, and optionally including failed endpoints or extended details.
• serviceendpoint_list_types: List the available service endpoint types.
• serviceendpoint_update [write]: Update an existing service endpoint from a raw body.

policy

• policy_create_configuration [write]: Create a new policy configuration within a project.
• policy_delete_configuration [write]: Delete a policy configuration from a project.
• policy_get_configuration: Get a single policy configuration by its ID.
• policy_list_configurations: List the policy configurations for a project, optionally filtered by policy type. Returns a continuationToken to fetch the next page when more configurations exist.
• policy_list_evaluations: List the policy evaluation results (pass/fail status of each required policy) for a pull request.
• policy_list_types: List the policy types available within a project.
• policy_update_configuration [write]: Update an existing policy configuration within a project from a raw body (isEnabled, isBlocking, type, settings, etc.).

search

• search_code: Full-text search across source code in the organization, optionally scoped to one or more projects, repositories, paths, or branches (comma-separated for multiple), sorted, faceted, and paged with top/skip.
• search_wiki: Full-text search across wiki pages in the organization, optionally scoped to one or more projects or wikis (comma-separated for multiple), sorted, faceted, and paged with top/skip.
• search_work_items: Full-text search across work items in the organization, optionally scoped to one or more projects and filtered by work item type, state, assigned-to identity, or area path (comma-separated for multiple), sorted, faceted, and paged with top/skip.

processes

• processes_add_field [write]: Add a field to a work item type within a process.
• processes_add_work_item_type [write]: Add a new work item type to a process.
• processes_create [write]: Create a new inherited process from a parent process (e.g. Agile, Scrum, CMMI, Basic).
• processes_create_behavior [write]: Add a behavior to a process.
• processes_delete [write]: Delete a process by its process type ID.
• processes_delete_behavior [write]: Remove a behavior from a process.
• processes_get: Get a single process by its process type ID.
• processes_list: List the work item tracking processes in the organization.
• processes_list_behaviors: List the behaviors defined within a process.
• processes_list_fields: List the fields of a work item type within a process.
• processes_list_states: List the workflow states of a work item type within a process.
• processes_list_work_item_types: List the work item types defined within a process, optionally expanding additional details (e.g. states).

entitlement

• entitlement_get_user: Get the access-level entitlement for a single user by entitlement id.
• entitlement_list_groups: List group entitlements (licensing rules) for the organization.
• entitlement_list_users: List user access-level entitlements (licensing) for the organization, optionally filtered ($filter) or continued via a continuation token.

notification

• notification_create_subscription [write]: Create a notification subscription from a raw body (description, filter, channel, etc., per the ADO subscription schema).
• notification_delete_subscription [write]: Delete a notification subscription by ID.
• notification_get_subscription: Get a single notification subscription by ID.
• notification_list_event_types: List the available notification event types in the organization.
• notification_list_subscriptions: List the notification subscriptions in the organization, optionally filtered by target identity.
• notification_update_subscription [write]: Update an existing notification subscription from a raw body.

extension

• extension_get: Get a single installed extension by its publisher and extension identifiers.
• extension_install [write]: Install an extension for the Azure DevOps organization.
• extension_list_installed: List all extensions installed in the Azure DevOps organization, optionally including disabled extensions, extensions with errors, and extensions with installation issues.
• extension_set_state [write]: Enable or disable an installed extension.
• extension_uninstall [write]: Uninstall an extension from the Azure DevOps organization.

tfvc

• tfvc_get_changeset: Get a single TFVC changeset by ID.
• tfvc_get_item: Get a TFVC item at the given path, including its content.
• tfvc_list_branches: List the TFVC branches, including child branches.
• tfvc_list_changesets: List TFVC changesets, optionally filtered by item path, author, date range, or version, optionally following renames or including shallow-reference links, with paging via top/skip.

advsec

• advsec_get_alert: Get a single Azure DevOps Advanced Security alert by its numeric ID.
• advsec_list_alerts: List Azure DevOps Advanced Security alerts for a repository, optionally filtered by alert type (code, secret or dependency), state, severity, git ref, or restricted to the default branch. Returns a continuationToken to fetch the next page when more alerts exist.

approvals

• approvals_create_check_configuration [write]: Create a check configuration on a protected resource from a raw body (type, settings, resource {type, id}, timeout, etc., per Azure DevOps' documented schema, which differs by check type: approval, branch control, business hours, REST API invocation, etc.).
• approvals_delete_check_configuration [write]: Delete a check configuration.
• approvals_get: Get a pipeline run approval by its identifier.
• approvals_get_check_configuration: Get a single check configuration by ID.
• approvals_list_check_configurations: List the check configurations defined on a protected resource (by resource type and id).
• approvals_update [write]: Approve or reject a pending pipeline run approval.
• approvals_update_check_configuration [write]: Update a check configuration from a raw body.

identities

• identities_read: Look up legacy identities by search filter (e.g. 'General', 'DisplayName', 'AccountName'), filter value or descriptors, optionally including membership data (queryMembership: None, Direct, or Expanded).

operations

• operations_get: Get the status of a long-running asynchronous Azure DevOps operation by its operation ID.

profile

• profile_get_me: Retrieve the profile of the authenticated user.

macro

• macro_complete_pull_request [write]: Complete (merge) a pull request. Fetches the PR's last merge commit automatically, then merges with the chosen options.
• macro_create_bug [write]: Create a Bug work item from common fields (title, repro steps, severity, assignee, area/iteration), optionally adding a comment in the same call.
• macro_publish_wiki_page [write]: Create or update a wiki page at a path with the given Markdown content, reporting whether it was created or updated.
• macro_publish_wiki_page_with_images [write]: Upload images as wiki attachments and create/update a page that embeds them. In the Markdown content, reference each image with the placeholder {{att:NAME}} (NAME matching an image's name); it is replaced with the attachment path. Image content must be base64-encoded; it is decoded before upload.

stats

• stats_builds: Build outcomes (success/failure rates) per definition for a project.
• stats_org_contributors: Contribution stats aggregated across every repository in every project in the organization. Can be slow on large orgs.
• stats_project_contributors: Contribution stats aggregated across every repository in a project.
• stats_pull_requests: Pull-request activity per author and by status, for a repo or for a whole project (omit repo).
• stats_repo_contributors: Contribution stats (commits and change counts per author) for one repository. Optionally filter by date range.
• stats_work_items: Work item breakdown by type, state, and assignee for a project (optionally scoped by a WIQL query).

favorites

• favorites_create [write]: Create a favorite for the caller, from a raw body ({artifactId, artifactType, artifactName, artifactScope: {type, id}}) per the ADO favorite schema.
• favorites_delete [write]: Remove one of the caller's favorites by its ID.
• favorites_list: List the caller's favorites (organization-wide), optionally filtered by a comma-separated list of artifact types (e.g. 'Microsoft.TeamFoundation.WorkItemTracking.WorkItemQuery' for a saved query, 'Microsoft.TeamFoundation.Dashboards.Dashboard' for a dashboard).

deliveryplans

• deliveryplans_get: Get a single delivery plan's metadata by ID.
• deliveryplans_list: List the delivery plans defined in a project.

notes

• notes_add [write]: Record a new note: a session or event against a project, environment, service, version, repo, branch, and/or users, with a summary, optional body, and an optional start/stop time range. Date defaults to today.
• notes_delete [write]: Delete a note by ID.
• notes_get: Get a single note by ID.
• notes_get_config: Get a stored notes config value by key (e.g. a remembered default like "default_project"). Returns an empty value if unset.
• notes_list: List notes, newest first. Filter by an exact date or date range, by project/env/service/version/repo/branch/user, and/or by a free-text search over summary and body.
• notes_list_config: List every stored notes config key/value pair.
• notes_list_values: List the distinct values already used for one field (project, env, service, version, repo, branch, or users) across all notes, sorted alphabetically. Useful for suggesting existing values instead of asking cold.
• notes_pull_sevenpace [write]: Fetch 7pace worklogs (optionally filtered with an OData $filter) and create one note per worklog (date/start/stop/summary). Only registered when 7pace is configured.
• notes_push_sevenpace [write]: Send a note's date/start/stop/summary (only — not body, project, or other fields) to 7pace as a new worklog. The note must have both start and stop set. Only registered when 7pace is configured.
• notes_set_config [write]: Set (creating or overwriting) a notes config key/value pair, e.g. to remember a default project or service for future notes.
• notes_summary: Aggregate notes over a date (or date range): total notes and minutes/hours (from notes with both start and stop set), plus per-day and per-project breakdowns.
• notes_update [write]: Update fields of a note. Omitted fields are left unchanged.

sevenpace

• sevenpace_create_worklog [write]: Create a new 7pace worklog (timestamp, length in seconds, comment, optional linked work item ID). Uses a separate, best-effort write API base (SEVENPACE_REST_BASE) since the integrated Reporting API is read-only; verify against a real account before relying on it.
• sevenpace_list_budgets: List the configured 7pace budgets.
• sevenpace_list_work_items: List work items with their rolled-up tracked time (the workItems entity). Supports an OData $filter.
• sevenpace_list_worklog_workitems: List 7pace worklogs joined with their Azure DevOps work items (the workLogsWorkItems entity). Supports an OData $filter.
• sevenpace_list_worklogs: List 7pace worklogs (the workLogsOnly entity). Filter with an OData $filter such as "Timestamp ge 2026-01-01T00:00:00Z".
• sevenpace_query: Run a raw GET against the 7pace Reporting OData API and return the response body. Use for entity sets or options not covered by the other tools, or path "$metadata" to inspect the schema. Entity sets include workLogsOnly, workLogsWorkItems, workItems, budgets.

Prompts (workflows)

Prompts and composite macros

MCP has no dedicated "workflow" primitive, so multi-step flows are shipped two ways:

Prompts: user-invoked templates that clients surface as slash commands. Each guides the model through a sequence of tool calls. Built-in prompts:

Prompt	Arguments	What it does
triage_bug	project, id	Load a work item, summarize it, propose & apply state/assignee/priority
review_pr	project, repo, pullRequestId	Summarize a PR and its threads, surface risks, offer to comment/vote
sprint_status	project, team	Current iteration scope, board state, items at risk
explore_repo	project, repo	Branches, recent commits, structure, README summary
update_wiki_page	project, wiki, path, topic	Draft/confirm content, then create or update a wiki page
new_note	summary	Interactively create a note, suggesting field defaults from past notes
log_my_day	date, totalHours	List my active work items and log 7pace time against them

MCP clients surface these prompts as slash commands automatically (e.g. in Claude Code and Claude Desktop), so each is available as a slash command named after the prompt once the server is connected.

Composite macro tools (macros toolset): single tools that orchestrate several REST calls server-side, for flows that are awkward one call at a time:

• macro_complete_pull_request: fetches the PR's last merge commit, then merges with the chosen options.
• macro_create_bug: creates a Bug from common fields and optionally adds a comment in one call.
• macro_publish_wiki_page: creates or updates a wiki page and reports which it did.

Architecture

Project layout

cmd/ado                entrypoint: a urfave/cli command tree (mcp, test, note)
internal/config        environment configuration + validation
internal/client        generic JSON REST client (auth, api-version, paging, error mapping)
internal/server        MCP server wrapper, typed tool registration, read-only policy
internal/ado           Azure DevOps connection (one REST client per service host)
internal/ado/<area>    one package per service area: <area>.go (operations) + tools.go (tools)
internal/sevenpace     7pace Timetracker integration
internal/notes         local notes store (SQLite): notes + key/value config, optional 7pace sync

The mcp subcommand loads config, registers the enabled toolsets, and serves over stdio; test checks credentials; note operates on the local notes store.

Each service area follows the same shape: a service wrapping the shared REST clients exposes typed operations, and a Register function registers thin MCP tool handlers for them. Adding a new area is a matter of dropping in a package and listing it in cmd/ado. See the docs site's Architecture page for the full request-flow walkthrough.

Development

Build, test, and smoke-test

make test        # go test -race ./...
make cover       # run tests and print a coverage summary
make vet         # go vet ./...
make fmt-check   # gofmt verification
make lint        # golangci-lint
make all         # fmt-check + vet + lint + test + build

Releases are tag-triggered (GoReleaser via CI); make next/make bump compute and tag the next version from conventional commits. See the docs site's Development page for the full releasing workflow.

Smoke-testing the protocol

List the tools over stdio without an MCP client:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"s","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| ADO_ORG_URL=https://dev.azure.com/myorg ADO_PAT=$ADO_PAT ./bin/ado mcp

Or browse interactively with the MCP Inspector:

npx @modelcontextprotocol/inspector ./bin/ado mcp

Changelog

See CHANGELOG.md.

License

MIT. See LICENSE.