# Integrations & Read API

# Integrations & Read API

Hand an external AI agent or script a **capability grant** (API key) so it can read your journal, bloods, daily plans, and profile — without copying JSON by hand.

## Where to start

1. Open **Account → Integrations** on the main app (`/account/integrations`).
2. Acknowledge health-data consent, then use **Connect Claude**, **Connect Cursor**, or **Connect Grok** (each mints its own labeled key).
3. Copy the **remote MCP URL** + auth snippet for your platform (no clone, no npm install).
4. Optional: click **Test connection** before leaving the browser. Prefer tool `get_snapshot` or prompt `pregnancy_briefing` once connected.

Revoke any time. **Revoke all** is the panic button. Share Portfolio (`/account/shares`) is for human read-only links — different from API keys.

## Remote MCP (recommended)

Hosted endpoint (same channel as the Read API):

- Production: `https://api.beingoptimal.org/mcp`
- Development: `https://api-dev.beingoptimal.org/mcp`

Send `Authorization: Bearer bo_live_…`. Works with Claude Desktop, Claude Code, Cursor, and Grok CLI/Build.

**Note:** claude.ai web/mobile and grok.com “Add custom connector” do not yet accept a pasted key for individual users (OAuth is planned later).

Tools include `get_meta`, `get_context`, `get_journal`, `get_bloods`, `get_plans`, `get_plan_templates`, `get_profile`, and **`get_snapshot`** (adaptive briefing that follows `suggestedNext`). Resources: `beingoptimal://meta`, `beingoptimal://context`. Prompt: `pregnancy_briefing`.

## Advanced: local stdio MCP

1. Expand **Advanced / offline setup** on the mint success panel and download the stdio MCP config (embeds your key in `env` — keep private).
2. Copy the `integrations/mcp` folder from the Being Optimal repo (or install `@beingoptimal/mcp` after it is published), run `npm install` inside it.
3. Set `args` to the **absolute** path of `integrations/mcp/src/server.mjs`.
4. Set `BEING_OPTIMAL_API_BASE` to your channel (`https://api.beingoptimal.org` or `https://api-dev.beingoptimal.org`).

## What agents get

- Hydrated meal lines (`label` / `unit` / `basis`) on journal and plans
- Blood markers with ranges, flags, and trimester targets (units converted when possible)
- Weak `ETag` + `If-None-Match` → `304` when nothing changed
- HATEOAS `links` (`self`, `docs`, `related`, `next`)

## API hosts

- Production: `https://api.beingoptimal.org`
- Development: `https://api-dev.beingoptimal.org`

Full reference: the repo guide `docs/API.md` and OpenAPI at `docs/api/openapi.yaml`.

## Safety

- Keys are shown once; only a display prefix is stored.
- Reads are audited (who/what/when).
- Server-to-server only — do not embed keys in browsers.
- One key binds to one environment (same model as share links).
- Grant columns (scopes/hash) are immutable after mint; revoke is permanent.

<Related ids={["integrations-read-api", "export-download-delete-data"]} />