Connect MCP

AI clients talk to Chartbuddy Hub through the Model Context Protocol (MCP). Install Hub first: Windows or macOS.

How clients connect

Clients spawn the Chartbuddy binary with --mcp over stdio. That process talks to Chartbuddy Hub on loopback.

Framing: newline-delimited JSON-RPC (preferred) or Content-Length framed MCP. Responses match the request framing.

The MCP server ships inside the Chartbuddy binary. Nothing to npm install or launch with npx.

Client

AI client

Cursor, ChatGPT, Claude — spawns MCP over stdio.

Adapter

chartbuddy --mcp

Headless mode. Port file, or auto-launches Hub.

Runtime

Chartbuddy Hub

Desktop .app. Local HTTP bridge on loopback.

On macOS, auto-launch looks for Chartbuddy Hub in this order:

1. /Applications/Chartbuddy.app/Contents/MacOS/chartbuddy
2. ~/.local/bin/chartbuddy (optional symlink, Help → Install CLI Symlink…)
3. chartbuddy on your PATH
4. open -a Chartbuddy (Launch Services by name)

Pick your client

Client	Guide
Cursor	Connect Cursor
Claude (web)	Connect Claude (web)
Claude Code	Connect Claude Code
OpenCode	Connect OpenCode
Google Antigravity	Connect Google Antigravity
ChatGPT / Codex	Connect ChatGPT / Codex
ChatGPT (web)	Connect ChatGPT (web)

Shared config

Every client uses the same stdio spawn (args: --mcp):

Windows

{
  "mcpServers": {
    "Chartbuddy-Hub": {
      "type": "stdio",
      "command": "C:\\Users\\YOUR_USER\\AppData\\Local\\Programs\\Chartbuddy\\chartbuddy.exe",
      "args": ["--mcp"]
    }
  }
}

macOS

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

Verify

Status check (read-only)

Fast and synchronous. Never launches Chartbuddy Hub or opens UI:

Windows

& "$env:LOCALAPPDATA\Programs\Chartbuddy\chartbuddy.exe" --mcp-status

macOS

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

--mcp-doctor is an alias. Exit 0 = Chartbuddy Hub bridge up; 1 = unreachable.

If the port file exists and Chartbuddy Hub windows are visible but status says unreachable, you may be in a sandbox that denied loopback. Approve access and re-run.

Smoke test (optional)

Chartbuddy Hub must be running. Pipe newline JSON-RPC into --mcp:

Windows

@"
{"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":{}}}
"@ | & "$env:LOCALAPPDATA\Programs\Chartbuddy\chartbuddy.exe" --mcp

macOS

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

Command	Behavior
--mcp-status / --mcp-doctor	Facts + exit; no launch. --json / --setup optional
chartbuddy --mcp	Long-lived MCP adapter (stdio); may auto-launch Chartbuddy Hub on first tool call
Open Chartbuddy.app	Starts the Chartbuddy Hub GUI

Using tools

• list_charts lists Hub windows (chart-*) and CE edit sessions (ce:*), each with surface: tauri|ce.
• Edits usually target a specific chart_ref.
• get_active_chart returns a real chart window (not menus/popovers).
• Edits happen in Chartbuddy Hub’s desktop windows. Hub has no in-app prompt box.

Troubleshooting

Symptom	Check
MCP tools missing in chat	Config saved? MCP refreshed / new chat? Server enabled for that conversation?
Chartbuddy Hub not starting	Launch Chartbuddy Hub; run chartbuddy --mcp-status
Status “unreachable” but Chartbuddy Hub windows open	Sandbox may have denied loopback. Approve network for chartbuddy
Permission / Gatekeeper	Open Chartbuddy Hub from its install location the first time
Wrong window targeted	Use list_charts; ignore popover/menu windows
Stale port file	Quit Chartbuddy Hub, delete the Hub mcp-port file if needed (macOS / Linux ~/.chartbuddy/mcp-port, Windows %USERPROFILE%\.chartbuddy\mcp-port), relaunch
Project MCP config in git	Use user/global scope only
Client talking to the Hub mcp-port file as MCP	Client must spawn chartbuddy --mcp
Treating --mcp-status as a launcher	Read-only; open the app (or use --mcp tool calls) to start Hub