Configuring AI tools with the remote MCP server

This page explains how to configure your AI tool to work with the remote Buildkite MCP server.

The Buildkite MCP server is available both locally and remotely. This page is about configuring AI tools with the remote MCP server. If you are using an AI tool or agent and would prefer it to work with the local MCP server, ensure you have followed the required instructions on Installing the Buildkite MCP server locally first, before proceeding with the relevant instructions on its Configuring AI tools page.

Amp

You can configure Amp with the remote Buildkite MCP server, by adding the following JSON configuration to your Amp settings.json file, which requires the mcp-remote command argument to allow OAuth authorization. Learn more about this type of configuration in the Custom Tools (MCP) section of the Amp docs.

{
  "amp.mcpServers": {
    "buildkite": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.buildkite.com/mcp"
      ]
    }
  }
}

Once connected to the remote MCP server, if you need a new OAuth token, the Authorize Application for the Buildkite MCP Server page appears. If so, scroll down and select your Buildkite organization in Authorize for organization, followed by Authorize.

You're now ready to use Buildkite's remote MCP server through Amp for this Buildkite organization.

Toolsets and read-only access

To enable toolsets or configure read-only access, or both, for the remote MCP server with Amp, you can implement the following headers to this configuration, for example:

{
  "amp.mcpServers": {
    "buildkite-read-only-toolsets": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.buildkite.com/mcp/readonly",
        "--header",
        "X-Buildkite-Toolsets: user,pipelines,builds"
      ]
    }
  }
}

This example applies read-only access to all toolsets specified in the X-Buildkite-Toolsets header. However, you can be selective over which toolsets have read-only access. Learn more about this in Selective read-only access to toolsets.

Alternatively, instead of using headers, you could also use the URL extension approach by creating multiple MCP server configurations—one for each toolset. Ensure you provide an appropriate name for each MCP server configuration to make it easier to identify which toolsets and level of access each server has to the Buildkite API.

Claude Code

You can configure Claude Code with the remote Buildkite MCP server by running the relevant Claude Code command, after installing Claude Code.

claude mcp add --transport http buildkite https://mcp.buildkite.com/mcp

You're now ready to use Buildkite's remote MCP server through Claude Code for this Buildkite organization.

Toolsets and read-only access

To enable toolsets or configure read-only access, or both, for the remote MCP server with Claude Code, you can add the following header configurations to this command, for example:

claude mcp add --transport http buildkite-read-only-toolsets https://mcp.buildkite.com/mcp/readonly --header "X-Buildkite-Toolsets: user,pipelines,builds"

Claude Desktop

You can configure Claude Desktop with the remote Buildkite MCP server, by creating a custom connector for this MCP server in Claude Desktop.

This process assumes you are on an Enterprise or Team plan (with either the Owner or Primary Owner role), or a Pro or Max plan for Claude Desktop.

Select Settings > Connectors.

Note: If you're on an Enterprise or Team plan, select Admin settings > Connectors instead.
Towards the end of the Connectors page, select the Add custom connector button.
In the Add custom connector dialog, for the Name field, specify Buildkite.
For the Remote MCP server URL field, specify https://mcp.buildkite.com/mcp.
Select Add to complete the configuration.
On the Settings > Connectors page, select the Connect button for Buildkite to connect to the remote MCP server.

Note: If you are on the Enterprise or Team plan, to access this Connect button, you may need to select the Your connectors tab first.

If you need a new OAuth token, the Authorize Application for the Buildkite MCP Server page appears. If so, scroll down and select your Buildkite organization in Authorize for organization, followed by Authorize.

You're now ready to use Buildkite's remote MCP server through Claude Desktop for this Buildkite organization.

If you need more assistance with this process, follow Anthropic's guidelines for Getting Started with Custom Connectors.

Toolsets and read-only access

To enable toolsets or configure read-only access, or both, for the remote MCP server with Claude Desktop, follow this create custom connector procedure by implementing the URL extension approach when enabling the toolset, with the following updates:

For the Name field, specify a name that better describes the customer connector. For example, Buildkite - pipelines toolset for the pipelines toolset.
For the Remote MCP server URL field, specify the enabled toolset for the remote MCP server. For example, https://mcp.buildkite.com/mcp/x/pipelines.

Note: If you also want to enforce read-only access for the tools in this toolset, append /readonly to this URL, for example, https://mcp.buildkite.com/mcp/x/pipelines/readonly.

Repeat this process for each toolset you want to enable. You'll end up with multiple custom connectors for the Buildkite MCP server, and to use them together, you'll need to connect to each one you want to use during your Claude Desktop sessions.

Cursor

You can configure Cursor with the remote Buildkite MCP server by adding the relevant configuration to your Cursor's mcp.json file, which is usually located in your home directory's .cursor sub-directory.

From your Cursor Settings, select MCP & Integrations.
Under MCP Tools, select Add Custom MCP to open the mcp.json file.
Implement the following update to this file, where if you have other MCP servers configured in Cursor, just add the "buildkite": { ... } object to this JSON file.

{
  "mcpServers": {
    "buildkite": {
      "url": "https://mcp.buildkite.com/mcp"
    }
  }
}

You're now ready to use Buildkite's remote MCP server through Cursor for this Buildkite organization.

Toolsets and read-only access

To enable toolsets or configure read-only access, or both, for the remote MCP server with Cursor, you can implement the following headers to this configuration, for example:

{
  "mcpServers": {
    "buildkite-read-only-toolsets": {
      "url": "https://mcp.buildkite.com/mcp/readonly",
      "headers": {
        "X-Buildkite-Toolsets": "user,pipelines,builds"
      }
    }
  }
}

Goose

Goose is a local AI tool and agent that can be configured with different LLM (AI model) providers.

You can configure Goose with the remote Buildkite MCP server by adding the relevant configuration to the extensions: section of your Goose config.yaml file.

extensions:
  buildkite:
    enabled: true
    type: streamable_http
    name: buildkite
    uri: https://mcp.buildkite.com/mcp
    envs: {}
    env_keys: []
    headers: {}
    description: ''
    timeout: 300
    bundled: null
    available_tools: []

You're now ready to use Buildkite's remote MCP server through Goose for this Buildkite organization.

Toolsets and read-only access

To enable toolsets or configure read-only access, or both, for the remote MCP server with Goose, you can implement the following headers to this configuration, for example:

extensions:
  buildkitereadonlytoolsets:
    enabled: true
    type: streamable_http
    name: buildkitereadonlytoolsets
    uri: https://mcp.buildkite.com/mcp/readonly
    envs: {}
    env_keys: []
    headers:
      X-Buildkite-Toolsets: user,pipelines,builds
    description: ''
    timeout: 300
    bundled: null
    available_tools: []

Visual Studio Code

You can configure Visual Studio Code with the remote Buildkite MCP server by adding the relevant configuration to your Visual Studio Code's mcp.json file.

{
  "servers": {
    "buildkite": {
      "url": "https://mcp.buildkite.com/mcp",
      "type": "http"
    }
  }
}

Alternatively, you can initiate this process through the Visual Studio Code interface. To do this:

In the Command Palette, find and select the MCP: Add Server command.
Select HTTP (HTTP or Server-Sent Events) to start configuring a remote MCP server.
For Enter Server URL, specify https://mcp.buildkite.com/mcp.
For Enter Server ID, specify buildkite.

Follow the remaining prompts to complete this configuration process.

You're now ready to use Buildkite's remote MCP server through Visual Studio Code for this Buildkite organization.

Toolsets and read-only access

To enable toolsets or configure read-only access, or both, for the remote MCP server with Visual Studio Code, you can implement the following headers to your mcp.json configuration file, for example:

{
  "servers": {
    "buildkite-read-only-toolsets": {
      "url": "https://mcp.buildkite.com/mcp/readonly",
      "type": "http",
      "headers": {
        "X-Buildkite-Toolsets": "user,pipelines,builds"
      }
    }
  }
}

Windsurf

You can configure Windsurf with the remote Buildkite MCP server by adding the relevant configuration to your Windsurf's mcp_config.json file.

{
  "mcpServers": {
    "buildkite": {
      "url": "https://mcp.buildkite.com/mcp"
    }
  }
}

You're now ready to use Buildkite's remote MCP server through Windsurf for this Buildkite organization.

Toolsets and read-only access

To enable toolsets or configure read-only access, or both, for the remote MCP server with Windsurf, you can implement the following headers to your mcp_config.json configuration file, for example:

{
  "mcpServers": {
    "buildkite-read-only-toolsets": {
      "url": "https://mcp.buildkite.com/mcp/readonly",
      "headers": {
        "X-Buildkite-Toolsets": "user,pipelines,builds"
      }
    }
  }
}