# MCP

Connect AI agents to Buddy over the Model Context Protocol (MCP) to run pipelines, manage deployments, sandboxes, packages, domains, and more.

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.

## Server URLs

Point your agent 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 two authentication modes:

- **Interactive OAuth** - the agent opens a browser to log in and approve scopes. This is the smoothest option for desktop clients like Claude Code and Cursor: point them at the server URL and you'll be prompted to authenticate on first use.
- **Headless (token)** - use a [personal access token](/docs/api/getting-started/oauth2/introduction.md) as a `Bearer` header. This suits CI pipelines and custom agents where no browser is available:

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

## Connecting an agent

Most MCP clients accept a server entry like this:

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

For step-by-step setup in a specific tool - including the exact command or config file - see the [agents](/docs/ai-agents/agents.md) pages.

## Tool filtering

The server exposes **over 90 tools** across every category. Limit the visible categories with the `?tools=` query parameter, passing a comma-separated list:

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

Narrowing the tool set keeps the agent focused and reduces the number of tools it has to reason about.

## Available tool categories

- `user`
- `workspaces`
- `projects`
- `members`
- `pipelines`
- `source`
- `targets`
- `sandboxes`
- `packages`
- `domains`
- `distros`
- `suites`

## Safety

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

<Hint type="warning">
Start with a narrowly-scoped token and read-only access while you experiment, then expand permissions as you build trust in the agent. Use [tool filtering](#tool-filtering) to expose only the categories a given agent actually needs.
</Hint>


---
Original source: https://buddy.works/docs/ai-agents/mcp