+++
title = "Using Bonsai with AI agents"
description = "The ways an AI agent can manage Bonsai clusters: an agent skill, an MCP server, the API, and docs in Markdown."
weight = 19
updated = 2026-11-11

[extra]
nav_title = "Overview"
weight = 10
+++

An AI agent can manage your Bonsai clusters the way you would: create a cluster for a project, put its connection URL where your app reads it, check how close it is to its plan's limits, and tell you what your users search for.

Everything an agent needs comes with the [Bonsai CLI](@/docs/cli/overview/index.md), a single binary for macOS and Linux:

```bash
bonsai login                              # once, in your own terminal
bonsai skill install                      # teach Claude Code to use the CLI
claude mcp add bonsai -- bonsai mcp       # or connect an MCP client
```

Then ask:

> Create a sandbox OpenSearch cluster for this project and put its URL in `.env`.

## Ways to connect an agent

| | What it is | Best for |
|---|---|---|
| [**Agent skill**](@/docs/cli/agent-skill/index.md) | Instructions that teach an agent to run the `bonsai` CLI | Agents with a shell: Claude Code, Codex, Cursor's agent |
| [**MCP server**](@/docs/cli/mcp-server/index.md) | `bonsai mcp`, a local [Model Context Protocol](https://modelcontextprotocol.io) server with 18 tools | Clients that call tools: Claude Desktop, Cursor, VS Code, and Claude Code too |
| [**API**](@/docs/api/overview/index.md) | A REST API with an OpenAPI description and an `llms.txt` | Agents you build yourself, and anything without the CLI |
| [**Docs in Markdown**](@/docs/agents/docs-and-api/index.md) | Every page of these docs, served as Markdown on request | Agents that read documentation while they work |

The skill and the MCP server give an agent the same abilities, and you can use both.

## Set it up

- [Claude Code](@/docs/agents/claude-code/index.md): the skill, the MCP server, or both.
- [Claude Desktop, Cursor, VS Code and Codex](@/docs/agents/mcp-clients/index.md): the MCP server, client by client.
- [Other agents](@/docs/agents/other-agents/index.md): add Bonsai's instructions to `AGENTS.md` or your agent's rules file.

## Learn more

- [What agents can do](@/docs/agents/what-agents-can-do/index.md): the tasks, with example prompts.
- [Keeping agents safe](@/docs/agents/safety/index.md): scopes, read-only mode, passwords and confirmations.
- [Docs and API for agents](@/docs/agents/docs-and-api/index.md): Markdown docs, the OpenAPI description and `llms.txt`.

## How it's built for agents

Agents make different mistakes than people do, so the CLI and the MCP server are built around them:

- **The agent never sees your API token.** You log in once in your own terminal, and the token stays in your system keychain. It doesn't go in a chat or in a client's config file.
- **The agent never sees a cluster's password.** It writes the connection URL straight into a git-ignored env file, and gets the URL back with the password masked.
- **Destroying a cluster needs its name.** Typed out, as a confirmation, by you.
- **Changes that cost money are confirmed first.** The skill tells the agent to name the cluster, plan and region and ask you before it creates, resizes or destroys.
- **A read-only mode.** `bonsai mcp --read-only` leaves out every tool that changes a cluster, and a token without the `clusters:write` scope can't change one at all.
- **Machine-readable everything.** `--json` on every command, exit codes that say what went wrong, and no prompts that an agent would hang on.

See [Keeping agents safe](@/docs/agents/safety/index.md).

## Building search for agents

This section is about agents that manage your clusters. If you're building an agent that searches, with retrieval-augmented generation, vector search or hybrid search on Elasticsearch or OpenSearch, see:

- [AI Powered Search](@/docs/ai-search/ai-powered-search/index.md), [Vector Search](@/docs/ai-search/vector-search/index.md) and [Hybrid Search](@/docs/ai-search/hybrid-search/index.md).
- [Agentic Search Models with OpenSearch and Elasticsearch](@/blog/agent-search-with-sid/index.md).
- [What AI Engineers Should Know About Search](@/blog/what-ai-engineers-should-know-about-search/index.md).