Skip to main content

​
Install

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

​
Configuration

The server reads its configuration from the environment:
  • 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.
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

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:

​
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.
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

This writes to ~/.codex/config.toml, which you can also edit directly:
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

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.