Connect getbased to external AI assistants

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-08-08: newly joined Sync devices now complete their relay restore before reloading, Agent Access controls load in place the first time you open Settings, and external agents receive the complete redesigned health context.

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

You turn on Cross-device Sync and Agent Access in Settings.
getbased creates two Agent Access values:
- GETBASED_TOKEN — read-only relay authorization.
- GETBASED_AGENT_CONTEXT_KEY — local AES-GCM decryption key.
The browser signs the gateway write with your Sync owner identity so storage/quota are bound to that identity, not to a random token.
The gateway stores only ciphertext and maps your token to that Sync owner.
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.

The Data sources switches in Insight → Manage → Context control in-app AI chat, Biology Score context, and source-driven warnings. Agent Access is a separate external-sharing permission in Settings → Agent Access. When Agent Access is on, the browser builds the encrypted gateway summary from the full available profile context, including specialty lab groups and wearable summaries. To keep external agents from reading that summary, turn Agent Access off or regenerate/remove its credentials.

What an agent receives

Agent Access encrypts the same structured context text assembled for in-app AI, then exposes its named sections through the local MCP client. Depending on the profile, that can include:

lab values, effective reference ranges, trends, specialty lab groups, marker notes, and flagged-result summaries;
all nine health-context cards, profile notes, and the context change timeline;
supplements and medications, cycle context, curated genome findings, Light & Sun context, and the compact wearable summary; and
an optional 7-, 30-, or 90-day wearable series that you enable separately.

Answered context fields remain meaningful even when they rule something out. The summary includes skin type and explicit digestive answers such as None or Normal; unanswered fields are omitted rather than guessed. The in-app Data sources switches do not filter Agent Access. External sharing is controlled by the separate Settings → Agent Access toggle because the browser must produce a consistent complete summary for the MCP tools. The gateway receives only the encrypted envelope; plaintext becomes available only after your local MCP client decrypts it with GETBASED_AGENT_CONTEXT_KEY.

Setup

Enable Sync and Agent Access

Open Settings → Cross-device Sync and make sure Sync is enabled.
Open Settings → Agent Access.
Toggle Agent Access on.
Choose your setup target: Hermes Agent, OpenClaw, Claude Code, Claude Desktop, Cursor, Cline, or Codex CLI.
Click Copy setup command.

The copied command looks like this:

curl -fsSL https://getbased.health/install.sh | bash -s -- connect <target> --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 (public agent path)

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.

curl -sSL https://getbased.health/install.sh | bash

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 --local-only   # 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.

Paste the setup command into your agent machine

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:

curl -fsSL https://getbased.health/install.sh | bash -s -- connect <target> --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.

Query your labs

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:

getbased-stack mcp-config <target>

The supported target names are hermes, openclaw, claude-code, claude-desktop, cursor, cline, and codex.

Hermes Agent config example

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:

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:

getbased-stack mcp-config hermes

Paste the output into ~/.hermes/config.yaml, then restart Hermes:

hermes gateway restart

The generated snippet looks like this:

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:

Open getbased on the device that has the correct local profile data.
Confirm Sync is enabled with the new mnemonic.
Open Settings → Agent Access.
Pick the same setup target you use for that agent.
Click Copy setup command.
Paste the new command into the terminal where your agent runs:

curl -fsSL https://getbased.health/install.sh | bash -s -- connect <target> --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.

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, Withings, Ultrahuman, self-hosted Google Health, Apple Health, legacy Fitbit, or manual entries) and Agent Access is on, the agent automatically receives a [section:wearables] block when it calls getbased_lab_context. The block is compact and includes current value, baseline, weekly trend, and recent anomaly events for each metric. The in-app Body → Wearable recovery context switch does not filter Agent Access; external sharing is controlled from Settings → Agent Access. 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 compact 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

If you log Sun & Light sessions, the agent can pull them via getbased_section('sun'). The section is generated from the same Light & Sun context as the browser: sun sessions, light-device sessions, indoor light environment, channel doses, atmosphere, eye-exposure mode, and body-exposure summaries when present. The earlier separate body-region detail toggle has been folded into the Light & Sun source. Detailed body-region keys are treated as Light & Sun context; precise location still stays out unless a caller explicitly asks for it through the session APIs.

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

Agent sees the wrong profile

The gateway serves whichever profiles have been pushed from your browser. If the agent returns data for the wrong person:

Open getbased and switch to the correct profile.
Make any edit and save (or toggle Agent Access off and back on) to force a fresh push.
Ask the agent again — use the profile ID parameter if you have multiple profiles.

Agent returns stale data

The gateway is updated whenever you save changes in getbased. If answers seem outdated:

Confirm Agent Access is still toggled on in Settings → Agent Access.
Open getbased in your browser — the push happens from the browser, so it needs to be open at least once after your latest changes.
Check your network connection — the push requires internet access to reach the gateway.

Token not working

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.

Agent can fetch context but cannot decrypt it

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.

Agent cannot reach the gateway

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.

Getting Started

Labs

Genome

Body & Wearables

Light & Environment

Insight & AI

Data, Sync & Backup

Advanced

Connect getbased to external AI assistants

How it works

What an agent receives

Setup

Advanced MCP tools reference

Supported clients and manual config

Hermes Agent config example

Advanced/manual Hermes config

Sync mnemonic changes and relay recovery

Multi-profile support

Wearable data in agent context

30-day daily series (opt-in)

Sun & Light sessions

Security

Troubleshooting

​How it works

​What an agent receives

​Setup

​Advanced MCP tools reference

​Supported clients and manual config

​Hermes Agent config example

​Advanced/manual Hermes config

​Sync mnemonic changes and relay recovery

​Multi-profile support

​Wearable data in agent context

​30-day daily series (opt-in)

​Sun & Light sessions

​Security

​Troubleshooting

How it works

What an agent receives

Setup

Advanced MCP tools reference

Supported clients and manual config

Hermes Agent config example

Advanced/manual Hermes config

Sync mnemonic changes and relay recovery

Multi-profile support

Wearable data in agent context

30-day daily series (opt-in)

Sun & Light sessions

Security

Troubleshooting