AI Assistant Integration (MCP)

Deploy Azure DevOps branches from your AI coding assistant using the Model Context Protocol.

Supported Clients

BranchDeploy exposes a standard remote MCP server (Streamable HTTP), so it works with any MCP-compatible client. Setup below is provided for the main ones:

Claude (claude.ai, Desktop and mobile) & Claude Code
ChatGPT, where the BranchDeploy app is enabled for your account or workspace
GitHub Copilot (VS Code)
Cursor
Any other MCP-compatible AI client

Prerequisites

A BranchDeploy workspace, on any plan (see what each plan can do)
An Azure DevOps PAT saved in the workspace by an admin, for previews and deploys. It's shared by everyone in the workspace. You can connect before it's added.
At least one deployment environment configured and synced (via the Azure DevOps extension)

What each plan can do from an assistant

Any workspace can connect an AI assistant. What it can do depends on the workspace's plan, checked on every request, so a plan change applies straight away without reconnecting.

Free: list environments, check deployment history and status, and preview what a ticket would deploy (its branch, environment and pipeline). To deploy, use the Deploy button on the ticket in Azure DevOps.
Pro: everything in Free, plus deploying from the assistant and drafting, previewing and publishing release notes.

If a Pro subscription is past due or cancelled, the workspace gets Free access until billing is sorted out in the account app.

Setup

Step 1: Connect Azure DevOps

In your BranchDeploy account, open the Credentials tab and add an Azure DevOps PAT with Work Items (Read), Code (Read), and Build (Read & Execute) scopes (Execute lets the MCP server queue a pipeline run). Also add Extension Data (Read), under Show all scopes, so your assistant can tell you when a teammate is holding the environment. Without it, deploys still work but holds aren't checked. If you already saved a PAT for the Teams bot, verify it includes Build (Read & Execute) before using MCP deployments.

The PAT is BranchDeploy's own access to Azure DevOps, and one PAT serves the whole workspace: an admin saves it once, and every member's assistant deploys go through it. We recommend creating it from a service account: otherwise every Teams and AI deploy shows in Azure DevOps as the person the PAT belongs to, and stops working if they leave.

Step 2: Generate an MCP API key for direct MCP clients

In your account page, open the Credentials tab and, under Your MCP API key, click Generate key. Copy the key — it is shown once only. ChatGPT and Claude sign in with BranchDeploy OAuth instead, so skip this step if that is all you use.

Each person in a workspace generates their own key; don't share one. A key acts as the person who made it: it can only do what their role allows, deployments it queues are recorded under their name, and it stops working if they leave the workspace. Admins can see and revoke every member's key from the same page. The key only gets the assistant into BranchDeploy; BranchDeploy then carries out the deploy in Azure DevOps through the workspace PAT from Step 1.

Step 3: Add to your AI client

BranchDeploy is a remote HTTP MCP server at https://mcp.branch-deploy.dev/mcp, authenticated with your MCP API key as a bearer token for direct MCP clients, or with BranchDeploy OAuth for ChatGPT and Claude. Configure whichever client you use below — replace your-mcp-api-key with the key from Step 2 where applicable.

Claude (claude.ai, the Desktop app and mobile) connects as a custom connector and signs in with your BranchDeploy account, so there's no config file and no API key to paste.

In Claude, open Settings → Connectors and choose Add custom connector. On a Team or Enterprise plan, an owner adds it once from the organisation's connector settings.
Name it BranchDeploy and enter https://mcp.branch-deploy.dev/mcp as the URL.
Click Connect, choose Sign in with BranchDeploy, and approve the access shown on the consent screen.
In a chat, turn BranchDeploy on from the tools menu in the composer, then ask it to deploy a ticket.

Connectors added on claude.ai also appear in the Desktop and mobile apps. Previews and deploys need a saved Azure DevOps PAT, and deploying needs Pro. Claude asks before every deploy or publish, and BranchDeploy refuses a deploy that wasn't previewed first.

Using an API key instead

If you'd rather use the MCP API key from Step 2, Claude Desktop's config file only accepts local (stdio) servers, so it connects through the mcp-remote bridge (needs Node.js for npx).

Open Settings → Developer → Edit Config, or edit the file directly: ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows.
Merge the snippet below into the file, keeping any servers you already have.
Fully quit Claude (⌘Q on macOS, tray icon → Quit on Windows) and reopen it — closing the window is not enough.
Open the tools menu in the composer; branchdeploy should be listed.

{
  "mcpServers": {
    "branchdeploy": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.branch-deploy.dev/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer your-mcp-api-key"
      }
    }
  }
}

Put the token in env (not inline after --header) so the space in Bearer … isn't split into a separate argument.

Claude Code talks to remote MCP servers directly. One command registers it.

Run the command below in your project. Add -s user to register it for every project instead of just this one.
Check it connected with claude mcp list.
Inside Claude Code, run /mcp to see the BranchDeploy tools.

claude mcp add --transport http branchdeploy https://mcp.branch-deploy.dev/mcp \
  --header "Authorization: Bearer your-mcp-api-key"

VS Code reads MCP servers from .vscode/mcp.json — note it uses the servers key, not mcpServers.

Create .vscode/mcp.json in your workspace with the snippet below.
Save the file, then click Start in the code lens above the server entry.
Open Copilot Chat and switch it to Agent mode.
Open the tools picker and confirm the BranchDeploy tools are selected.

{
  "servers": {
    "branchdeploy": {
      "type": "http",
      "url": "https://mcp.branch-deploy.dev/mcp",
      "headers": {
        "Authorization": "Bearer your-mcp-api-key"
      }
    }
  }
}

.vscode/mcp.json is usually committed to the repo. To avoid checking your key in, use a ${input:…} placeholder so VS Code prompts for it, or add the server globally with MCP: Add Server from the command palette.

Cursor supports remote MCP servers directly, globally or per project.

Create ~/.cursor/mcp.json for every project, or .cursor/mcp.json inside one project.
Open Cursor Settings → MCP and check branchdeploy shows as connected.
Use it from the Agent — the tools appear automatically.

{
  "mcpServers": {
    "branchdeploy": {
      "url": "https://mcp.branch-deploy.dev/mcp",
      "headers": {
        "Authorization": "Bearer your-mcp-api-key"
      }
    }
  }
}

Any MCP client that supports remote Streamable HTTP servers works. Point it at https://mcp.branch-deploy.dev/mcp and send the header Authorization: Bearer your-mcp-api-key. Clients such as Windsurf, Cline and Zed follow the same URL + bearer-header pattern. Older clients that only speak SSE can use https://mcp.branch-deploy.dev/sse instead.

Clients cache the tool list from the moment they connect. After changing this config, restart the client fully rather than reloading the window.

Step 4: Try it

Ask your AI assistant:

"Deploy ticket 2372"
"Deploy ticket 4185 to Staging" — name an environment only if the project has more than one
"Show me recent deployments"
"Draft release notes from recent UAT deployments"

You only give the ticket number. The AI shows you the work item, resolved branch, and target environment, and always asks for confirmation before anything is queued.

Available Tools

Tool	What it does
`preview_deploy`	Resolves the work item, branch, environment, and branch rules without queueing anything.
`deploy`	Queues the configured Azure Pipeline after validation and explicit confirmation.
`list_environments`	Lists the deployment environments configured for a project.
`get_deployment_status`	Checks a deployment by the deployment ID returned from `deploy`.
`get_deployment_history`	Lists recent deployments for a project, optionally filtered by work item ID.
`list_release_note_candidates`	Lists recent deployments and release-note feeds that can be used as source material.
`get_work_item_details`	Reads deployment-backed work item details when AI context is enabled for the organisation.
`list_release_notes`	Lists existing draft, published, or archived release notes.
`create_release_note_draft`	Creates a draft release note that is not visible to customers.
`update_release_note_draft`	Updates an existing draft release note after feedback.
`preview_release_note`	Returns the exact public JSON that would be published and a short-lived confirmation token.
`publish_release_note`	Publishes a confirmed release note to the public feed using the preview confirmation token.
`archive_release_note`	Withdraws a release note from the public feed after explicit confirmation.

How It Works

Deploying through the assistant does exactly what the deploy button on the work item does — nothing more. The AI can't pick an arbitrary branch or pipeline; BranchDeploy resolves and validates everything server-side:

You say "deploy ticket 2372"
BranchDeploy looks up the work item, its project, and the branch linked to it
It picks the environment whose branch rules allow the linked branch (or asks which, if more than one does)
It checks the linked branch is permitted by that environment's branch rules — and refuses if not
The AI shows you the plan and asks you to confirm
After you confirm, BranchDeploy queues the environment's configured pipeline on that branch

Because the branch, pipeline, and rules all come from your project configuration — never from the assistant — an AI (or a prompt) cannot deploy a branch that isn't linked to the ticket or one your environment doesn't allow.

Release Notes

BranchDeploy can also help draft customer-facing release notes from deployments it has already recorded. Drafts stay private until you preview the exact public JSON and explicitly confirm publishing.

The assistant lists release-note candidates from deployment history.
It can read work item details only when AI context is enabled for the organisation.
It creates or updates a private draft using customer-facing wording.
It previews the public JSON and asks you to confirm.
Only after confirmation does it publish to the public release-note feed.

Troubleshooting

"Invalid MCP API key"
Regenerate the key in your account settings and update your client config.

"No Azure DevOps PAT configured"
Add a PAT in your account, on the Credentials tab.

"Isn't included in this workspace's current BranchDeploy plan"
The workspace is on Free, which can preview a deploy but not run one from an assistant. See what each plan can do. The Deploy button on the ticket works on every plan.

"Work item not found"
Check the ticket number and ensure the PAT has access to that project.

"No environments configured"
Open the project's Project Settings → BranchDeploy in the extension, check a connection token is connected (BranchDeploy account), and click Save all environments to sync its environments to the cloud.