> For the complete documentation index, see [llms.txt](https://bluebricks.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bluebricks.co/docs/integrations/bricks-mcp.md).

# Bluebricks MCP

The Bluebricks MCP (Model Context Protocol) server lets AI agents discover blueprints, deploy infrastructure, and manage environments through natural language.

{% embed url="<https://youtu.be/O4VG8jzBBOM>" %}

## How it works

You describe what you need, the agent translates it into Bluebricks operations:

1. **Request**: "Create a PostgreSQL database with Redis cache for staging"
2. **Plan**: the agent shows resource changes, cost estimates, and security considerations
3. **Deploy**: you approve the plan, and the agent applies it

<figure><img src="/files/ULNelGvJ5qCjJU38BsdX" alt=""><figcaption></figcaption></figure>

## Getting started

<details>

<summary><strong>VS Code</strong></summary>

[![Install in VS Code](https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square\&label=Install%20Server\&color=0098FF)](https://vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22bricks%22%2C%22command%22%3A%22bricks%22%2C%22args%22%3A%5B%22mcp%22%5D%7D)

Manually install the MCP extension for VS Code:

1. Open VS Code Extensions (`Ctrl+Shift+X` or `Cmd+Shift+X`)
2. Search for "Model Context Protocol"
3. Install the MCP extension
4. Open Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`)
5. Run "MCP: Add Server"
6. Configure server:
   * **Name**: `bricks`
   * **Command**: `bricks`
   * **Args**: `["mcp"]`

</details>

<details>

<summary><strong>Claude Desktop</strong></summary>

Add the Bricks MCP server to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "bricks": {
      "command": "bricks",
      "args": ["mcp"]
    }
  }
}
```

Configuration file location:

* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
* **Linux**: `~/.config/claude-desktop/claude_desktop_config.json`

</details>

<details>

<summary><strong>Cursor</strong></summary>

Enable MCP support in Cursor settings:

1. Open Cursor Settings (`Cmd+,` or `Ctrl+,`)
2. Navigate to Extensions → MCP
3. Add new server configuration:
   * **Name**: `bricks`
   * **Command**: `bricks`
   * **Args**: `["mcp"]`

</details>

<details>

<summary><strong>Windsurf</strong></summary>

Configure MCP in your Windsurf workspace:

```json
{
  "mcp": {
    "servers": {
      "bricks": {
        "command": "bricks",
        "args": ["mcp"],
        "env": {}
      }
    }
  }
}
```

Add this configuration to your `.windsurf/settings.json` file.

</details>

<details>

<summary><strong>Other MCP Clients</strong></summary>

For any MCP-compatible client, configure with:

* **Command**: `bricks`
* **Arguments**: `["mcp"]`
* **Protocol**: `STDIO`

Consult your client's documentation for specific configuration steps.

</details>

### Authentication

Authenticate using your existing Bricks CLI credentials:

```bash
bricks login
```

## Example prompts

**Resource discovery**

```
What blueprints are available for GCP workloads?
```

```
Show me all collections and their current status
```

```
Find database blueprints with high availability configuration
```

**Infrastructure planning**

```
Plan a development S3 bucket matching the one on production
```

```
Deploy the PostgreSQL blueprint to my staging collection
```

**Environment management**

```
Approve my latest staging environment
```

```
Show me the status of my recent AWS environments
```

```
List all pending environments that need my approval
```

## Available tools

| Tool                        | Description                                                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------- |
| `bricks_list_blueprints`    | List blueprints with fuzzy search and pagination                                                |
| `bricks_list_collections`   | List and search collections with full context, including latest environments and cloud accounts |
| `bricks-list-environments`  | List environments with filtering for latest, all activities, or archived                        |
| `bricks_install`            | Install a blueprint to a collection, or update an existing environment                          |
| `bricks_deployment_approve` | Approve an environment plan to proceed with infrastructure changes                              |
| `bricks_deployment_reject`  | Reject an environment plan to prevent infrastructure changes                                    |

## Tool annotations

Each tool declares [MCP tool annotations](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#annotations) that describe its behavior. MCP clients can use these hints to decide which tools to auto-approve and which to prompt for confirmation.

| Tool                        | readOnlyHint | destructiveHint | idempotentHint | openWorldHint |
| --------------------------- | :----------: | :-------------: | :------------: | :-----------: |
| `bricks_list_blueprints`    |     true     |      false      |      true      |      true     |
| `bricks_list_collections`   |     true     |      false      |      true      |      true     |
| `bricks-list-environments`  |     true     |      false      |      true      |      true     |
| `bricks_install`            |     false    |      false      |      false     |      true     |
| `bricks_deployment_approve` |     false    |       true      |      false     |      true     |
| `bricks_deployment_reject`  |     false    |       true      |      false     |      true     |

**What the annotations mean:**

* **readOnlyHint**: the tool does not modify any state
* **destructiveHint**: the tool may perform an action that cannot be easily undone
* **idempotentHint**: calling the tool again with the same arguments has no additional effect
* **openWorldHint**: the tool interacts with external systems beyond the local environment

{% hint style="info" %}
Annotations are hints, not security guarantees. Do not make access-control decisions based solely on these values.
{% endhint %}