CLI or MCP?
Both surfaces hit the same data. Pick by where the agent runs.
Quick decision
| If you are… | Use |
|---|---|
| Building a script, cron job, or shell pipeline | CLI |
| Calling from a Claude Code, Cursor, or Windsurf session | MCP |
| Inside Claude Desktop or ChatGPT (developer mode) | MCP |
| Running an autonomous OpenClaw / BetterClaw agent | Either — often both (MCP for tool calls, CLI inside subprocess) |
| Writing a backend service against the REST API | Direct REST, but consider MCP for tool semantics |
What both surfaces guarantee
- Same auth model (
bk_*API keys; OAuth additionally for CLI interactive flows) - Same rate limits and audit logging
- Same data model — biomarkers, lab orders, wearable readings — returned in JSON
- Same governance — every call requires a consent grant for the relevant data category
Where they differ
| CLI | MCP | |
|---|---|---|
| Distribution | npm install -g @betterness/cli | JSON config in your client |
| Output | Text or --json | JSON tool results returned over HTTP |
| Composability | Pipe to jq, scripts, other CLIs | Tool calls inside agent reasoning loops |
| Latency | Cold-start each invocation | Long-lived session |
| Discovery | betterness --help, betterness schema | Tool list returned by tools/list |
Can I use both?
Yes. They share credentials — the CLI's betterness mcp install <client> command writes the same API key into your MCP client config. A common pattern is to keep the CLI for cron and shell utilities while using MCP inside an editor or assistant.