> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bonya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Install and connect the Bonya MCP server

## Install

```bash theme={null}
npm install -g @bonya-ai/bonya-mcp
# or run without installing:
npx @bonya-ai/bonya-mcp
```

This installs the `bonya-mcp` executable, which speaks MCP over stdio.

## Configuration

The server reads its configuration from the environment:

| Env var | Required | Default |
| - | - | - |
| `BONYA_API_KEY` | yes | — |
| `BONYA_ENDPOINT` | no | `https://api.bonya.ai` |
| `BONYA_ORGANIZATION_ID` | no | caller's personal organization |

* `BONYA_API_KEY` is a personal API key (`byk_...`), sent as a bearer token on every request.
* `BONYA_ENDPOINT` overrides the API base URL if you need to point at a non-default environment.
* `BONYA_ORGANIZATION_ID`, if set, is sent as the `X-Bonya-Organization-ID` header to scope every call to a specific organization instead of your personal one.

> [!NOTE]
>
> The server doesn't validate `BONYA_API_KEY` at startup — it resolves configuration lazily on the first tool call, so the server can start and advertise its tools even before the key is set. A missing or invalid key surfaces as a normal tool error rather than a startup crash.

## Connect a client

Every client below launches `bonya-mcp` as a local process over stdio and passes it environment variables — the same `mcpServers`/`mcp_servers` shape each time, just in a different config format. `BONYA_ENDPOINT` and `BONYA_ORGANIZATION_ID` are optional in every example; add them the same way as `BONYA_API_KEY` if you need them.

### Claude Code

```bash theme={null}
claude mcp add bonya --env BONYA_API_KEY=your_key_here -- bonya-mcp
```

This registers the server for the **current project directory only** — an already-running session needs a full restart (not just a retry) to pick it up, since MCP servers only connect at session startup. Add `-s user` to make it available in every project instead:

```bash theme={null}
claude mcp add bonya -s user --env BONYA_API_KEY=your_key_here -- bonya-mcp
```

### Claude Desktop

Claude Desktop has no CLI shortcut — edit its config file directly, then fully quit and reopen the app (not just close the window). Open the file from Claude Desktop itself: the **Claude** menu (macOS menu bar, not an in-window menu) → **Settings** → **Developer** tab → **Edit Config**. The file lives at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%\Claude\claude_desktop_config.json` on Windows.

```json theme={null}
{
  "mcpServers": {
    "bonya": {
      "command": "bonya-mcp",
      "env": {
        "BONYA_API_KEY": "your_key_here",
        "BONYA_ORGANIZATION_ID": "your_org_id"
      }
    }
  }
}
```

If Claude Desktop reports it can't find `bonya-mcp`, it's usually a `PATH` problem — GUI apps on macOS don't always see the same `PATH` your terminal does, so a global install (`npm install -g @bonya-ai/bonya-mcp`) is the more reliable option there. Per-server logs live at `~/Library/Logs/Claude/mcp-server-bonya.log` (macOS) or `%APPDATA%\Claude\logs` (Windows) if a server fails to start.

### Codex

```bash theme={null}
codex mcp add bonya --env BONYA_API_KEY=your_key_here -- bonya-mcp
```

This writes to `~/.codex/config.toml`, which you can also edit directly:

```toml theme={null}
[mcp_servers.bonya]
command = "bonya-mcp"

[mcp_servers.bonya.env]
BONYA_API_KEY = "your_key_here"
```

> [!NOTE]
>
> The table name must be exactly `mcp_servers` (snake\_case) — Claude's `mcpServers` key from the JSON examples above doesn't carry over; Codex won't recognize it.

### ChatGPT

> [!WARNING]
>
> Plain ChatGPT at chatgpt.com **cannot** run `bonya-mcp` — it only connects to MCP servers reachable over the network (a public URL, or OpenAI's Secure MCP Tunnel for a private one), never a local command. If you only use ChatGPT in the browser, there's no stdio path for a local server like this one.

The ChatGPT **desktop app** is a separate surface built on the same underlying host as Codex, and as of writing supports local stdio servers via **Settings → MCP servers → Add server** (choosing **STDIO**), or by editing `~/.codex/config.toml` directly since it shares that file with Codex. This has moved between releases before, so check OpenAI's current docs if a config option described here doesn't match what you see.

## Errors

Non-2xx responses from the API are surfaced to the MCP client as tool errors, formatted as `Bonya API error <status> (<code>): <detail>` — for example `Bonya API error 409 (session_exists): a live session named "dev" already exists`. `code` and `detail` come from the API's RFC 9457 `application/problem+json` error body; `code` is the stable, machine-readable identifier and is more reliable to branch on than the HTTP status alone.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.