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 Desktop & 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

BranchDeploy Pro licence
Azure DevOps PAT connected (see account settings)
At least one deployment environment configured and synced (via the Azure DevOps extension)

Setup

Step 1: Connect Azure DevOps

In your BranchDeploy account at branch-deploy.dev/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). If you already saved a PAT for the Teams bot, verify it includes Build (Read & Execute) before using MCP deployments.

Step 2: Generate an MCP API key

In your account page, open the Credentials tab, find MCP API Key, and click Generate key. Copy the key — it is shown once only.

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. Configure whichever client you use below — replace your-mcp-api-key with the key from Step 2.

Claude Desktop's config file only accepts local (stdio) servers, so a remote server like BranchDeploy 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 Desktop's built-in Add custom connector only supports OAuth sign-in, not the static API key BranchDeploy uses, so the mcp-remote bridge is how you connect — on every plan.

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"

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.

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 selects the project's environment (or asks which, if there is more than one)
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.

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.

"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 and click Save — this syncs its environments to the cloud automatically.