+++
title = "Bonsai hosted MCP server"
description = "Add one URL to Claude, ChatGPT, Cursor or Claude Code, sign in to Bonsai, and let an agent manage your clusters and the data in them. Nothing to install."
weight = 20
updated = 2026-11-18

[extra]
nav_title = "Hosted MCP server"
weight = 15
+++

Bonsai runs a [Model Context Protocol](https://modelcontextprotocol.io) server for you:

```
https://mcp.bonsai.io/mcp
```

Add that URL to an app that supports MCP servers, sign in to Bonsai in your browser, and the app's agent gets tools to create and watch your clusters, and to create indices, load documents and search in them. There is nothing to install and no API token to paste.

It works with **Claude**, **ChatGPT**, **Cursor** and **Claude Code**. For other clients, such as VS Code and Codex, use the [local MCP server](@/docs/agents/mcp-clients/index.md) that comes with the Bonsai CLI.

## Connect an app

### Claude

In Claude on the web or the desktop app, open **Settings**, then **Connectors**, and add a custom connector with the URL `https://mcp.bonsai.io/mcp`. Click **Connect** and sign in.

### ChatGPT

Add a connector with the URL `https://mcp.bonsai.io/mcp` in ChatGPT's settings, and sign in when it asks. Custom connectors depend on your ChatGPT plan and its settings.

### Cursor

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

```json
{
  "mcpServers": {
    "bonsai": {
      "url": "https://mcp.bonsai.io/mcp"
    }
  }
}
```

Cursor opens the sign-in page the first time it uses the server.

### Claude Code

```bash
claude mcp add --transport http bonsai https://mcp.bonsai.io/mcp
```

Then run `/mcp` in Claude Code and pick **bonsai** to sign in.

## Sign in

The first time an app connects, it opens a Bonsai page in your browser. Log in if you aren't already, then:

1. **Pick the account.** You see the accounts where you can create API tokens.
2. **Pick the scopes.** These decide what the agent can do. Only `account:read` and `clusters:read` come checked, so by default the agent can look and can't change anything. See [what to allow](#scopes).
3. **Pick how long it lasts**: 30, 90 or 365 days.
4. **Approve.** Nothing is approved without that click, even for an app you approved before.

Approving creates an ordinary [API token](@/docs/account/api-tokens/index.md). It is listed in your account's API Tokens tab with the app's name, and Bonsai emails you that the app connected. When the token expires, the app asks you to sign in again.

The page names the app that is asking. For some apps it adds that the name is unverified: anyone can register an app under any name. Bonsai only sends you back to an app it supports, or to a program on your own computer, so an app with a borrowed name gets nothing from your approval. Still, approve only a request you started.

### What to allow {#scopes}

| To let the agent | Check |
|---|---|
| Look at clusters, usage, metrics, plans and regions | `account:read`, `clusters:read` (checked already) |
| Create, rename, resize and destroy clusters | `clusters:write` |
| Read what is in your clusters: list indices, search, count | `data:read` |
| Also change what is in them: create and delete indices, add and remove documents | `data:write` |
| Read your clusters' top search terms | `query_logs:read` |

A data scope brings `credentials:read` with it, because the server reaches a cluster with the cluster's own credential. The [scopes reference](@/docs/api/authentication/index.md#scopes) has every scope.

When a tool needs a scope the connection doesn't have, it says which one. To add it, disconnect Bonsai in the app, connect again, and check the scope. An approval can't be changed afterwards.

## The tools

There are 18, the ones [`bonsai mcp`](@/docs/cli/mcp-server/index.md#tools) has, with the same names and arguments, without `write_cluster_url`.

| Tool | What it does | Scope |
|---|---|---|
| `whoami` | The account the connection belongs to | `account:read` |
| `list_plans`, `list_regions`, `list_spaces`, `list_releases` | What you can create clusters with | `account:read` |
| `list_clusters`, `get_cluster` | Your clusters, and one cluster's state, plan, region, release, host and usage | `clusters:read` |
| `get_cluster_usage` | Docs, shards and size against the plan's limits, over time | `clusters:read` |
| `get_cluster_metrics` | Request rates, errors, traffic and latency, over time | `clusters:read` |
| `list_cluster_actions`, `get_action`, `wait_action` | A cluster's changes, and following one until it finishes | `clusters:read` |
| `get_cluster_top_queries` | The most frequent search terms | `query_logs:read` |
| `create_cluster`, `rename_cluster`, `resize_cluster`, `destroy_cluster` | Changes to clusters | `clusters:write` |
| `cluster_request` | One request to a cluster's own API | `data:read` or `data:write` |

Every tool is listed whatever you allowed. A tool you didn't allow answers with the scope it needs.

## Working with a cluster's data {#cluster-request}

`cluster_request` sends one request to a cluster's own API, Elasticsearch's or OpenSearch's, and returns the status and the cluster's answer. It is how an agent goes from managing a cluster to using one:

> Create an index called `breeds` on `good-dogs` and load these 200 dog breeds into it.

> Which hypoallergenic breeds live the longest?

The agent sends requests like these:

```
PUT /breeds

POST /breeds/_bulk
{ "index": {} }
{ "name": "Affenpinscher", "hypoallergenic": true }

GET /breeds/_search
{ "query": { "term": { "hypoallergenic": true } } }
```

| Argument | |
|---|---|
| `cluster` | The cluster's ID or name |
| `method` | `GET`, `HEAD`, `POST`, `PUT` or `DELETE` |
| `path` | The path and query, such as `/breeds/_search?size=5` |
| `body` | The request's body: JSON, or NDJSON for `_bulk` and `_msearch` |
| `confirm` | The index's name, typed out, for a request that deletes one |
| `credential` | A credential's ID. The default is the cluster's default credential |
| `timeout_seconds` | How long the cluster has to answer. The default is 15, and 20 is the most |

What to know about it:

- **`data:read` only reads.** With it, the tool sends `GET` and `HEAD` requests and nothing else. A search has to go as a `GET` with a body, which Elasticsearch and OpenSearch accept. `data:write` sends anything, reads included.
- **The password stays on the server.** The server reads the cluster's credential for that one call and sends the request with it. The agent gets the cluster's answer, never the password or the connection URL.
- **Deleting an index needs its name.** `DELETE /<index>` and `_delete_by_query` are refused unless `confirm` is the index's name, and the tool tells the agent to get it from you. Other requests that remove data, such as deleting one document or removing an index through `_aliases`, are not held back this way.
- **It is sized for a conversation.** A body of up to 1 MiB, an answer of up to 256 KiB, and about 20 seconds per request. An answer over the limit is an error that says how to ask for less. For a large load, use [`bonsai cluster request`](@/docs/cli/cluster-data/index.md) from the CLI.
- **Sending twice can apply twice.** After a timeout or a broken connection, the cluster may have applied the request. The tool tells the agent to check before it sends a write again.
- **Your documents are untrusted text** once they are in the agent's context, like any search result. The tool tells the agent to treat them as data, never as instructions.

Bonsai blocks some of Elasticsearch's and OpenSearch's endpoints. See [Unsupported API endpoints](@/docs/platform/unsupported-api-endpoints/index.md).

## How it differs from `bonsai mcp`

| | Hosted server | [`bonsai mcp`](@/docs/cli/mcp-server/index.md) |
|---|---|---|
| Where it runs | On Bonsai, at `mcp.bonsai.io` | On your machine |
| Setup | A URL and a sign-in | [Install the CLI](@/docs/cli/install/index.md) and `bonsai login` |
| Clients | Claude, ChatGPT, Cursor, Claude Code | Any client that runs a local MCP server |
| Cluster data | `cluster_request`, with the `data:read` or `data:write` scope. A body of up to 1 MiB, and 20 seconds at most | `cluster_request`, with the `credentials:read` scope. No limit on the body, and up to 5 minutes |
| Connection URLs | No tool returns or writes one | `write_cluster_url` writes it to a git-ignored env file |
| Read-only | Leave `clusters:write` and `data:write` unchecked | `--read-only`, which also keeps `cluster_request` to `GET` and `HEAD`, and the token's scopes |
| `wait_action` | Waits 15 seconds by default, 20 at most | 60 seconds by default, 300 at most |

Use the hosted server for an agent in a chat app, and the local one for a coding agent that should wire a cluster into the project in front of it. You can use both.

## Disconnect

Delete the token in your account's [API Tokens](@/docs/account/api-tokens/index.md) tab. The app loses access within a minute. Then remove the server from the app.

## Troubleshooting

- **A tool says a scope is missing.** Disconnect and connect again, and check that scope on the Bonsai page.
- **`cluster_request` is missing, or still says a scope is missing after you connected again.** Start a new chat. Apps keep the tool list they loaded when the chat began.
- **A search is refused with `data:read`.** Ask the agent to send it as a `GET` with a body.
- **The Bonsai page says the app asked to send you somewhere it didn't register, or the app can't connect at all.** The hosted server works with Claude, ChatGPT, Cursor and Claude Code. Use the [local MCP server](@/docs/agents/mcp-clients/index.md) with anything else.
- **The app asks you to sign in again.** The token expired or was deleted. Sign in, and pick a longer expiration if you want one.
- **An MCP client that runs in a web page can't sign in.** The sign-in endpoints don't answer cross-origin requests from a browser page.
