> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getbased.health/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect getbased to external AI assistants
> Connect MCP-compatible AI assistants to getbased with a private setup command. The gateway stores only encrypted context; decryption happens locally.
Agent Access is an opt-in feature that lets an AI assistant you configure read your getbased context outside the browser tab. After you enable it in Settings, an MCP-compatible tool — such as a coding agent, terminal assistant, or messenger bot — can fetch the encrypted summary and answer questions about your labs. getbased shares only a pre-built encrypted context summary; your raw data, sync mnemonic, and Agent Context key never leave your browser unless you paste the key into your own local MCP client.
Updated 2026-06-25: Agent Access now supports one-paste private setup from Settings → Agent Access for Hermes Agent, OpenClaw, Claude Code, Claude Desktop, Cursor, Cline, and Codex CLI.
## How it works
When you enable Agent Access, getbased encrypts a text summary of your labs, context cards, supplements, goals, and notes in your browser, then pushes the encrypted envelope to the **context gateway**. Your agent authenticates to the gateway with a read-only token, fetches ciphertext, and decrypts it locally with your separate Agent Context key.
```
getbased (browser)
├─ signs the write with your Sync identity
├─ encrypts context with your Agent Context key
└─ pushes ciphertext ──▶ Context Gateway ◀── token fetch ── local MCP decrypt ── AI agent
```
1. You turn on Cross-device Sync and Agent Access in Settings.
2. getbased creates two Agent Access values:
* `GETBASED_TOKEN` — read-only relay authorization.
* `GETBASED_AGENT_CONTEXT_KEY` — local AES-GCM decryption key.
3. The browser signs the gateway write with your Sync owner identity so storage/quota are bound to that identity, not to a random token.
4. The gateway stores only ciphertext and maps your token to that Sync owner.
5. Your local MCP client fetches the encrypted envelope with `GETBASED_TOKEN` and decrypts it locally with `GETBASED_AGENT_CONTEXT_KEY`.
The gateway cannot read the summary. It only stores and forwards encrypted data. It contains no raw lab entries, no sync mnemonic, and no Agent Context key. The summary is refreshed automatically whenever you save changes in getbased.
## Setup
1. Open **Settings → Cross-device Sync** and make sure Sync is enabled.
2. Open **Settings → Agent Access**.
3. Toggle Agent Access **on**.
4. Choose your setup target: **Hermes Agent**, **OpenClaw**, **Claude Code**, **Claude Desktop**, **Cursor**, **Cline**, or **Codex CLI**.
5. Click **Copy setup command**.
The copied command looks like this:
```bash theme={null}
curl -fsSL https://getbased.health/install.sh | bash -s -- connect --setup 'gbsetup_v1_...'
```
The setup command is private. It contains the read token and local context-decryption key needed to connect your own agent. Paste it only into a terminal you control. Public agent docs can explain how to install getbased, but only this app-generated command can grant access to your encrypted context.
Install **getbased-agent-stack** if you want the full local setup: the MCP adapter, the local knowledge-base server, and a browser dashboard. This public install command only installs software. It does not give access to your lab data; access requires the private setup command copied from getbased.
```bash Linux (one command) theme={null}
curl -sSL https://getbased.health/install.sh | bash
```
```bash macOS / Windows / manual theme={null}
pipx install --include-deps "getbased-agent-stack[full]"
# --include-deps is required — without it the MCP, RAG, and dashboard
# binaries from bundled dependencies aren't exposed on your PATH
getbased-stack init --yes # scaffolds config and starts services where supported
```
If you only want the MCP adapter without the RAG server, `pipx install getbased-mcp` is a smaller (\~10 MB) alternative.
After `install.sh` runs on Linux, it starts the knowledge server and a browser dashboard as systemd user services. Open the dashboard at `http://127.0.0.1:8323` to copy ready-made config blocks for supported clients. You do not need to write YAML or JSON by hand.
In the terminal where that agent runs, paste the command copied from getbased. The target in the command matches the chip you selected in Settings:
```bash theme={null}
curl -fsSL https://getbased.health/install.sh | bash -s -- connect --setup 'gbsetup_v1_...'
```
The command does the setup for you:
* stores the token and context key in `~/.config/getbased/env` with local-only permissions;
* registers `getbased-mcp` automatically when the selected client supports it;
* prints a paste-ready manual config snippet when a client cannot be auto-registered;
* runs a connection test;
* restarts or tells you how to restart the agent when the selected client needs a reload.
No manual YAML or JSON editing is required for the normal setup path.
Ask your agent anything about your labs. It reads your latest context from the gateway and responds. For example: "How is my iron trending?" or "What changed since my last blood draw?"
## Advanced MCP tools reference
Most users do not need this section. It is here for people checking what a connected assistant can call after setup.
`getbased-mcp` exposes the following tools to any connected agent:
| Tool | Description |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getbased_lab_context` | Full lab summary — values, reference ranges, trends, context cards, supplements, and goals. Accepts an optional profile ID; omit it to return the active profile. |
| `getbased_section` | Query a specific named section (e.g. `hormones`, `wearables`, `sun`) or list all available sections. |
| `getbased_wearables_series` | Daily wearable time-series (HRV, resting HR, sleep score, readiness, steps, weight, and more) over the 7-, 30-, or 90-day window you opt into. |
| `getbased_list_profiles` | List all profiles by name and ID. |
| `knowledge_search` | Semantic search over your knowledge base. Requires a local knowledge server (default `http://127.0.0.1:8322`, configurable via `LENS_URL`). If the server is not running, knowledge search will not work, but the lab-context tools still will. |
| `knowledge_list_libraries` | List all libraries on the RAG server with their IDs and which one is currently active. |
| `knowledge_activate_library` | Switch the active library. Subsequent searches target the new one. |
| `knowledge_stats` | Per-source chunk counts for the active library — useful for diagnosing missing search results. |
| `getbased_lens_config` | Show the Custom Knowledge Source endpoint and key from getbased so the agent stays in sync with what the app is configured to query. |
## Supported clients and manual config
In Settings → Agent Access, choose the tool you want to connect before copying the private setup command:
| Target | What the setup command does |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hermes Agent | Registers `getbased-mcp` through Hermes' MCP manager, stores secrets in the shared getbased env file, tests the connection, and restarts the gateway when safe. |
| OpenClaw | Stores the Agent Access secrets and prints the OpenClaw MCP config when automatic registration is not available. |
| Claude Code | Stores the Agent Access secrets and prepares the MCP config for Claude Code. |
| Claude Desktop | Stores the Agent Access secrets and prepares the desktop MCP config snippet. |
| Cursor | Stores the Agent Access secrets and prepares the Cursor MCP config snippet. |
| Cline | Stores the Agent Access secrets and prepares the Cline MCP config snippet. |
| Codex CLI | Stores the Agent Access secrets and prepares the Codex MCP config snippet. |
You can also ask the stack to print a config block for any supported target:
```bash theme={null}
getbased-stack mcp-config
```
The supported target names are `hermes`, `openclaw`, `claude-code`, `claude-desktop`, `cursor`, `cline`, and `codex`.
### Hermes Agent config example
[Hermes Agent](https://github.com/hermes-agent/hermes-agent) is a self-hosted AI assistant with built-in support for Matrix, Telegram, Signal, Discord, and other messengers. For Hermes, the normal path is the private bootstrap command copied after selecting **Hermes Agent** in **Settings → Agent Access**:
```bash theme={null}
curl -fsSL https://getbased.health/install.sh | bash -s -- connect hermes --setup 'gbsetup_v1_...'
```
It installs or upgrades the public getbased stack, stores secrets in the shared getbased env file, registers `getbased-mcp` through Hermes' MCP manager, tests the connection, and asks Hermes gateway to restart when safe.
### Advanced/manual Hermes config
If you need to configure Hermes manually, generate the snippet:
```bash theme={null}
getbased-stack mcp-config hermes
```
Paste the output into `~/.hermes/config.yaml`, then restart Hermes:
```bash theme={null}
hermes gateway restart
```
The generated snippet looks like this:
```yaml theme={null}
mcp_servers:
getbased:
command: getbased-mcp
args: []
env:
GETBASED_GATEWAY: https://sync.getbased.health
GETBASED_TOKEN: your-token-here
GETBASED_AGENT_CONTEXT_KEY: your-context-key-here
```
This keeps `GETBASED_TOKEN` and `GETBASED_AGENT_CONTEXT_KEY` out of Hermes config. If you prefer a single-file setup, you may put both values directly in the MCP server `env` block instead; explicit environment variables win over the shared stack env file.
## Sync mnemonic changes and relay recovery
Cross-device Sync and Agent Access use different secrets:
* The **Sync mnemonic** controls encrypted cross-device sync.
* `GETBASED_TOKEN` authorizes your agent's read from the context gateway.
* `GETBASED_AGENT_CONTEXT_KEY` decrypts the Agent Access context locally.
If you reset or regenerate your Sync mnemonic because the sync relay is wedged, pair your devices with the new mnemonic first, then force Agent Access to re-push under the new Sync owner:
1. Open getbased on the device that has the correct local profile data.
2. Confirm Sync is enabled with the new mnemonic.
3. Open **Settings → Agent Access**.
4. Pick the same setup target you use for that agent.
5. Click **Copy setup command**.
6. Paste the new command into the terminal where your agent runs:
```bash theme={null}
curl -fsSL https://getbased.health/install.sh | bash -s -- connect --setup 'gbsetup_v1_new...'
```
The reconnect command updates the shared local env file and re-tests the selected client. Because clients can read secrets from the stack-managed env file, you do not need to paste raw secrets into normal config files again.
7. Restart your agent or MCP client if it does not restart automatically.
The Sync mnemonic never goes into your agent config. Agents only need the Agent Access token and context key. Changing the Sync mnemonic means the browser must push Agent Access context again, because gateway writes are owner-bound.
## Multi-profile support
If you track labs for more than one person, each profile's context is stored separately on the gateway. Your agent can query any profile by ID:
* `getbased_list_profiles` returns all available profiles with names and IDs.
* `getbased_lab_context` accepts an optional profile ID parameter — omit it to get the currently active profile.
To update a profile's gateway context, switch to that profile in getbased, make any edit and save (or toggle Agent Access off and back on). The gateway receives that profile's latest context immediately.
## Wearable data in agent context
If you have wearables connected (Oura, Polar, WHOOP, Fitbit, Withings, Ultrahuman, Apple Health, or manual entries) and **Settings → AI → AI Context → Include wearable data** is on, the agent automatically receives a `[section:wearables]` block when it calls `getbased_lab_context`. The block is approximately 200 tokens and includes current value, baseline, weekly trend, and recent anomaly events for each metric.
To pull just the wearables section directly:
```
getbased_section('wearables', profile='Main')
```
### 30-day daily series (opt-in)
For time-series reasoning — "did my HRV drop the week before I got sick?" — the always-on summary is not enough. Open **Settings → Agent Access** and turn on **Push wearable daily series**. getbased then writes a pivoted daily matrix into a separate section:
```
getbased_section('wearables-series-30d', profile='Main')
```
The output looks like this:
```
[section:wearables-series-30d]
## Wearables — 30-day daily series (oldest→newest, "—" = no reading)
HRV (🌙) ms (oura): —→—→…→37→36→27→33→26→32→30→26→32→33→29→33→37→39→38→43→30
Resting HR bpm (oura): 64→62→61→…→59
Sleep (score) (oura): 68→72→75→…→72
Readiness (score) (oura): 58→61→63→…→69
Steps (oura): 7800→8200→…→4250
[/section:wearables-series-30d]
```
One line per metric, `→` separates daily values oldest-first, `—` means no reading that day. Raw daily samples never sync via the CRDT relay — they live in your browser's IndexedDB only. The browser renders the section string and posts it to the gateway.
## Sun & Light sessions (body regions opt-in)
If you log Sun & Light sessions, the agent can pull them via `getbased_section('sun')`. The default field set includes session date, duration, channel doses, atmosphere, eye-exposure mode, and a body summary.
The specific anatomical regions array (e.g. `['breast-chest', 'legs-front']`) is opt-in and off by default. Turn on **Settings → AI → AI Context → "Share body regions in Sun & Light context"** to include it. With the toggle off, the agent sees that you exposed roughly 45% of your body to the sun for 30 minutes, but not which 45%.
## Security
Agent Access is designed to share the minimum needed for an agent to be useful:
* **Relay token is not the encryption key** — `GETBASED_TOKEN` only authorizes reads from the gateway.
* **Separate local decryption key** — `GETBASED_AGENT_CONTEXT_KEY` decrypts the context locally in your MCP client. The gateway never receives it.
* **Owner-bound writes** — browser writes are signed with your Sync identity so relay storage and quotas are tied to your Sync owner, not to arbitrary tokens.
* **No raw data exposed** — the gateway stores an AES-GCM encrypted context envelope, not your underlying lab entries or personal records.
* **Mnemonic never leaves your browser** — Agent Access uses Sync identity only to prove ownership; it does not transmit your sync mnemonic.
* **Revocable at any time** — toggle Agent Access off in Settings to invalidate the token mapping. Click **Regenerate** to issue a new token and invalidate the old one.
* **Self-hostable** — the context gateway runs on the same server as the sync relay. Self-host both for full control over where encrypted summaries are stored.
Your token and context key together grant read access to your lab summary. Do not share them publicly or commit them to a public repository.
## Troubleshooting
The gateway serves whichever profiles have been pushed from your browser. If the agent returns data for the wrong person:
1. Open getbased and switch to the correct profile.
2. Make any edit and save (or toggle Agent Access off and back on) to force a fresh push.
3. Ask the agent again — use the profile ID parameter if you have multiple profiles.
The gateway is updated whenever you save changes in getbased. If answers seem outdated:
1. Confirm **Agent Access** is still toggled on in **Settings → Agent Access**.
2. Open getbased in your browser — the push happens from the browser, so it needs to be open at least once after your latest changes.
3. Check your network connection — the push requires internet access to reach the gateway.
`GETBASED_TOKEN` only authorizes the relay fetch. If the agent cannot fetch context at all:
* Make sure you copied the full token with no trailing spaces.
* Check that Agent Access is still enabled — disabling it invalidates the token immediately.
* If you clicked **Regenerate**, update your agent config with the new token — the old one no longer works.
`GETBASED_AGENT_CONTEXT_KEY` is separate from the token. A valid token with a missing, stale, or wrong context key must fail closed, so the MCP client will not show lab context until the key is fixed.
* Confirm your MCP config includes `GETBASED_AGENT_CONTEXT_KEY`, not just `GETBASED_TOKEN`.
* Copy the full **Context encryption key** from **Settings → Agent Access** with no trailing spaces.
* If you regenerated the context key, update your agent config and restart the MCP client or agent process.
* If the problem persists, regenerate both Agent Access values and replace both env vars together.
If you self-host the gateway, verify that:
* The gateway server is running and reachable from the agent's network.
* Your agent config points to the correct gateway URL (e.g. `https://sync.yourdomain.com`).
* TLS is configured correctly — the agent needs HTTPS access.