Buddy

npx add-mcp 'https://mcp.buddy.works/mcp'

MCP

View as Markdown

The Model Context Protocol (MCP) is an open standard that lets AI agents connect to external tools and data through a consistent interface. Buddy runs a remote MCP server, so an agent can actually do things in Buddy rather than just talk about them - imagine telling your assistant "deploy the latest version to production and tell me if anything breaks," and it runs the pipeline, watches it, and reports back.

Through MCP, an agent can trigger and monitor pipelines, manage deployments across environments, spin up sandboxes, publish packages, route domains, and pull build output and logs - all without leaving your workflow.

MCP is one of two ways to hook an agent up to Buddy. The Buddy skill teaches the agent to drive the bdy CLI on the machine it runs on; MCP gives it direct, typed access to the Buddy API. The two compose - with both in place the agent reaches for whichever fits the request.

Server URLs

If your client connects over HTTP, point it at the endpoint closest to your workspace region:

Region	URL
US	https://mcp.buddy.works/mcp
Europe	https://mcp.eu.buddy.works/mcp
Asia	https://mcp.asia.buddy.works/mcp

Authentication

The server supports three authentication modes:

• Interactive OAuth - the agent opens a browser to log in and approve scopes. The smoothest option for desktop clients like Claude Code and Cursor.
• Headless (token) - a personal access token in a Bearer header. For CI pipelines and custom agents where no browser is available.
• Buddy CLI - bdy mcp proxies to the server using the session from bdy login. Nothing to approve in a browser, no token in a config file.

The snippets below use the generic mcpServers shape that most clients accept. For the exact config file or command in a specific tool, see the agents pages.

Interactive OAuth

Point the client at the server URL with no credentials - you'll be prompted to log in and approve scopes on first use:

json
{
  "mcpServers": {
    "buddy": {
      "url": "https://mcp.buddy.works/mcp"
    }
  }
}

Headless (token)

Pass a personal access token as a Bearer header:

json
{
  "mcpServers": {
    "buddy": {
      "url": "https://mcp.buddy.works/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

Buddy CLI

Install and log in once:

bash
npm install -g bdy
bdy login
$$

Then register bdy mcp as a local server in your client. Agents with a built-in mcp add command take it directly:

bash
claude mcp add buddy -- bdy mcp --tools pipelines,source
codex mcp add buddy -- bdy mcp --tools pipelines,source
grok mcp add buddy -- bdy mcp --tools pipelines,source
$$$

Clients configured through a JSON file take the same command as a stdio entry:

json
{
  "mcpServers": {
    "buddy": {
      "command": "bdy",
      "args": ["mcp", "--tools", "pipelines,source"]
    }
  }
}

Omit --tools to expose all categories.

Info

The proxy acts as the logged-in CLI user and inherits their workspace access. Run bdy whoami to check which account is active, and bdy login to switch.

Tool filtering

The server exposes over 90 tools across every category. Narrowing the tool set keeps the agent focused and reduces the number of tools it has to reason about.

Over a remote URL, use the ?tools= query parameter with a comma-separated list:

https://mcp.buddy.works/mcp?tools=pipelines,source

Through the CLI, pass the same list to --tools:

bash
bdy mcp --tools pipelines,source
$

Available tool categories

Category	Scope
user	Current user account & profile
workspaces	Workspaces: list, create, settings
projects	Projects & configuration
members	Workspace/project members & permissions
pipelines	CI/CD pipelines, runs, actions
source	Repositories, branches, commits
targets	Deployment targets & servers
sandboxes	Ephemeral sandbox environments
packages	Artifact & package registries
domains	DNS zones & domains
distros	Distributions & routing
suites	Test suites (visual & unit)

Safety

MCP tools act on your real workspace, and some operations - deleting a project, tearing down a sandbox, removing a domain - are irreversible.

Warning

Start with read-only access while you experiment - a narrowly-scoped token, or a Buddy account whose permissions match what the agent really needs - then expand as you build trust. Use tool filtering to expose only the categories a given agent actually needs.