# Chartbuddy Hub — MCP setup

**This URL is documentation / a connect descriptor — not an MCP endpoint.**  
There is no MCP server on this host and no `/hub/openapi.json`.  
Clients connect by spawning the Chartbuddy **binary** with `--mcp` (stdio).

```
X-ChartBuddy-Resource: docs / agent-setup
X-ChartBuddy-MCP-Transport: stdio
```

Machine-readable twin: `/hub/mcp-setup.json` · Index: `/hub/llms.txt`  
Human docs (HTML): `/hub/docs/connect-mcp/`  
Per client (recommended first): `…/connect-mcp/cursor` · `…/connect-mcp/claude-code` · `…/connect-mcp/opencode` · `…/connect-mcp/chatgpt-codex` · `…/connect-mcp/chatgpt` · `…/connect-mcp/claude`

## Quickstart

| Field | Value |
|-------|--------|
| Transport | **stdio** (not HTTP) |
| Framing | **Newline-delimited JSON-RPC** (preferred) **or** Content-Length framed MCP |
| Command | `/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy` |
| Args | `--mcp` |
| Status | `…/chartbuddy --mcp-status` (read-only; never launches Hub) |

## Cursor — `~/.cursor/mcp.json` (user/global, do not commit) — recommended

```json
{
  "mcpServers": {
    "chartbuddy": {
      "type": "stdio",
      "command": "/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy",
      "args": ["--mcp"]
    }
  }
}
```

## Claude Code (user scope) — recommended

Also applies to the **Code** tab in the Claude desktop app (GUI for Claude Code).

```bash
claude mcp add-json chartbuddy '{"type":"stdio","command":"/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy","args":["--mcp"]}' --scope user
```

## OpenCode (global) — recommended

`~/.config/opencode/opencode.json` (or `.jsonc`). Top-level key is `mcp` (not `mcpServers`); `command` is one array (binary + args):

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "chartbuddy": {
      "type": "local",
      "command": ["/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy", "--mcp"],
      "enabled": true
    }
  }
}
```

## Claude (browser / desktop Home tab)

Hub MCP is **not** available here yet — no remote MCP endpoint. Use [Claude Code](#claude-code-user-scope) for Hub MCP, or the [Embed docs](https://chartbuddy.io/embed/docs/getting-started/) for charts in regular Claude chats.

## ChatGPT / Codex

For **Codex CLI** and the **Codex** tab in the ChatGPT desktop app:

1. **Settings** (bottom-left) → **Plugins** → **MCPs** tab → **+ Add server**
2. Type **STDIO**
3. Command: `/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy`
4. Arguments: `--mcp`
5. Save → keep Hub running → **new session**; approve loopback/network if prompted

Illustrated steps: `/hub/docs/connect-mcp/chatgpt-codex`

Desktop Codex tab may block tool calls with an OpenAI approval / “reasoning summaries” organization-verification error even when MCP is correct. Workarounds: Codex CLI, verify org at https://platform.openai.com/settings/organization/general, or use Cursor / Claude Code / OpenCode.

## ChatGPT (browser / regular desktop chat)

Hub MCP is **not** available here yet — no remote MCP endpoint. Use [ChatGPT / Codex](#chatgpt--codex) for Hub MCP, or the [Embed docs](https://chartbuddy.io/embed/docs/getting-started/) for charts in regular ChatGPT chats.

## Status check (read-only — never launches Hub)

```bash
/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy --mcp-status
```

Exit `0` = Hub bridge up; `1` = unreachable. Alias: `--mcp-doctor`.

## Hub must be running for a live bridge

```bash
open -a Chartbuddy
/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy --mcp-status
```

## Smoke test (newline JSON-RPC; Hub must be running)

```bash
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_charts","arguments":{}}}' \
| /Applications/Chartbuddy.app/Contents/MacOS/chartbuddy --mcp
```

Sample `tools/call` body:

```json
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_charts","arguments":{}}}
```

## After configuring a client

1. Refresh MCP / restart the client.
2. **Claude Code / Codex:** new session if tools are missing. **Cursor:** mid-chat attach usually works after refresh.
3. Optional handoff context:

```text
Chartbuddy MCP is configured (stdio → chartbuddy --mcp → Hub).
Transport: newline JSON-RPC or Content-Length framed MCP — not HTTP docs.
Open charts: list_charts — Hub chart-* and CE ce:* (surface tauri|ce). get_active_chart prefers a focused CE session when the extension bridge is connected.
create_chart surface=ce opens edit on the active Slides tab (extension + presentation required).
Missing tools usually mean the chartbuddy MCP server is off for the chat, or a new chat is needed.
```