+++
title = "Connect Claude Desktop, Cursor, VS Code and Codex to Bonsai"
description = "Add the Bonsai MCP server to Claude Desktop, Cursor, VS Code, Codex or any other MCP client."
weight = 21
updated = 2026-11-11

[extra]
nav_title = "Claude Desktop, Cursor, VS Code and Codex"
weight = 30
+++

`bonsai mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server that runs on your machine. Any MCP client can start it, and gets tools to list, create, change and watch your Bonsai clusters.

Every client needs the same two things: the command `bonsai`, and the argument `mcp`. Only the config file differs.

## Before you start

[Install the Bonsai CLI](@/docs/cli/install/index.md) and log in, in your own terminal:

```bash
bonsai login
```

The server uses the token that login stores in your system keychain, so no token goes in any config file below.

Desktop apps often don't see your shell's `PATH`. If a client can't find `bonsai`, use the full path from `which bonsai` as the `command`.

## Claude Desktop

Open **Settings**, then **Developer**, then **Edit Config**, and add the server to `claude_desktop_config.json`:

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

Restart Claude Desktop. The Bonsai tools appear in the tools menu of a new chat.

Claude Desktop starts the server outside your project, so `write_cluster_url` can't put a connection URL in your app's `.env`. Use Claude Desktop for looking at clusters and changing them, and a coding agent for wiring a cluster into an app.

## Cursor

Add the server to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for every project:

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

## VS Code

Add the server to `.vscode/mcp.json` in your workspace. VS Code names the key `servers`:

```json
{
  "servers": {
    "bonsai": {
      "type": "stdio",
      "command": "bonsai",
      "args": ["mcp"]
    }
  }
}
```

The tools are available to GitHub Copilot in agent mode.

## Codex

Add the server to `~/.codex/config.toml`:

```toml
[mcp_servers.bonsai]
command = "bonsai"
args = ["mcp"]
```

## Claude Code

```bash
claude mcp add bonsai -- bonsai mcp
```

See [Connect Claude Code to Bonsai](@/docs/agents/claude-code/index.md).

## Any other client

A client that supports MCP servers over stdio can run Bonsai's. Give it:

| | |
|---|---|
| Command | `bonsai` |
| Arguments | `mcp`, or `mcp --read-only` |
| Transport | stdio |
| Environment | None needed. `BONSAI_TOKEN` where there's no keychain |

## Read-only

Add `--read-only` to the arguments to leave out the tools that create, rename, resize and destroy clusters:

```json
"args": ["mcp", "--read-only"]
```

## Without a keychain

In a container, a remote dev environment or CI, there may be no keychain to log in to. Set `BONSAI_TOKEN` in the server's environment instead:

```json
{
  "mcpServers": {
    "bonsai": {
      "command": "bonsai",
      "args": ["mcp"],
      "env": { "BONSAI_TOKEN": "bonsai_<key>_<secret>" }
    }
  }
}
```

That puts a token in a file, so keep the file out of source control, and give the token only the [scopes](@/docs/api/authentication/index.md#scopes) the agent needs.

## The tools

| Tool | What it does |
|---|---|
| `whoami` | The account the token belongs to |
| `list_clusters`, `get_cluster` | Your clusters, and one cluster's state, plan, region, release, host and usage |
| `get_cluster_usage` | Docs, shards and size against the plan's limits, over time |
| `get_cluster_metrics` | Request rates, errors, traffic and latency, over time |
| `get_cluster_top_queries` | The most frequent search terms |
| `list_cluster_actions`, `get_action`, `wait_action` | A cluster's changes, and following one until it finishes |
| `list_plans`, `list_regions`, `list_spaces`, `list_releases` | What you can create clusters with |
| `write_cluster_url` | Writes a cluster's connection URL to a git-ignored env file |
| `create_cluster`, `rename_cluster`, `resize_cluster`, `destroy_cluster` | Changes. Left out with `--read-only` |

The [MCP server reference](@/docs/cli/mcp-server/index.md#tools) lists each tool's arguments.

## Troubleshooting

- **The client can't start the server.** Use the full path to `bonsai` as the `command`.
- **The server starts, then stops.** It needs a valid token. Run `bonsai doctor` in a terminal, then `bonsai login`.
- **The change tools are missing.** Check the arguments for `--read-only`.
- **`write_cluster_url` refuses the file.** It writes only below the folder the server started in, and only to a file that git ignores.