+++
title = "Connect Claude Code to Bonsai"
description = "Give Claude Code the Bonsai skill, the Bonsai MCP server, or both, and manage clusters by asking."
weight = 20
updated = 2026-11-11

[extra]
nav_title = "Claude Code"
weight = 20
+++

[Claude Code](https://claude.com/claude-code) can manage your Bonsai clusters in two ways: with a **skill**, which teaches it to run the `bonsai` CLI, or with the **MCP server**, which gives it tools to call. Each takes one command to set up.

## Before you start

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

```bash
bonsai login
bonsai whoami
```

The login opens a browser. Claude Code uses the token it stores, and never sees it.

## Option 1: the skill

```bash
bonsai skill install
```

This writes a [Claude Code skill](https://docs.claude.com/en/docs/claude-code/skills) to `~/.claude/skills/bonsai/SKILL.md`, where every project can use it. Claude Code loads it on its own when you ask about a Bonsai cluster, and runs `bonsai` in your shell.

To share it with your team, write it into the project and commit it:

```bash
bonsai skill install --project    # .claude/skills/bonsai/SKILL.md
```

Run `bonsai skill install` again after you upgrade the CLI, to bring the skill up to date.

## Option 2: the MCP server

Run this in your project folder:

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

Or, to have it in every project:

```bash
claude mcp add --scope user bonsai -- bonsai mcp
```

For an agent that should look and not touch, leave out the tools that change clusters:

```bash
claude mcp add bonsai -- bonsai mcp --read-only
```

Check it with `/mcp` in Claude Code, which lists the server and its tools.

## Which one?

- The **skill** needs no server, and Claude Code can combine `bonsai` with `jq`, `curl` and your own scripts.
- The **MCP server** has a read-only mode, and has no tool that returns a password.

You can install both. The skill tells Claude Code to write connection URLs with the MCP server's `write_cluster_url` tool when it's there.

## Try it

> What Bonsai clusters do I have, and how full is each one?

> Create a sandbox cluster called `blog-search` in us-east-1 and put its URL in `.env`.

> How has `search-prod` been doing over the last 24 hours? Any errors?

> What are the top search terms on `search-prod` this week? Which ones return few hits?

> `search-prod` is at 90% of its documents. Which plans would fit it, and what do they cost?

Before it creates, resizes or destroys a cluster, Claude Code tells you the cluster, plan and region, and asks. To destroy one, it asks you to type the cluster's name.

## In CI and headless runs

Where nobody can log in, set `BONSAI_TOKEN` instead, from your secret store:

```bash
export BONSAI_TOKEN=bonsai_<key>_<secret>
claude -p "Create a sandbox cluster named ci-$RUN_ID and write its URL to .env"
```

Give that token only the [scopes](@/docs/api/authentication/index.md#scopes) the job needs.

## Troubleshooting

- **Claude Code says there's no token.** Run `bonsai login` in your own terminal, then ask again. Don't paste a token into the chat.
- **The skill isn't used.** Check that `~/.claude/skills/bonsai/SKILL.md` exists, and start a new session.
- **The MCP server shows no tools.** Run `bonsai doctor`. The server exits when there's no valid token.
- **Writing `.env` is refused.** The file must be ignored by git. Add it to `.gitignore`.

See the [agent skill](@/docs/cli/agent-skill/index.md) and [MCP server](@/docs/cli/mcp-server/index.md) pages for every detail.