Skip to main content
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

Enable Sync and Agent Access

  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:
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.
2

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
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.
3

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.
4

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:
ToolDescription
getbased_lab_contextFull lab summary — values, reference ranges, trends, context cards, supplements, and goals. Accepts an optional profile ID; omit it to return the active profile.
getbased_sectionQuery a specific named section (e.g. hormones, wearables, sun) or list all available sections.
getbased_wearables_seriesDaily 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_profilesList all profiles by name and ID.
knowledge_searchSemantic 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_librariesList all libraries on the RAG server with their IDs and which one is currently active.
knowledge_activate_librarySwitch the active library. Subsequent searches target the new one.
knowledge_statsPer-source chunk counts for the active library — useful for diagnosing missing search results.
getbased_lens_configShow 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:
TargetWhat the setup command does
Hermes AgentRegisters getbased-mcp through Hermes’ MCP manager, stores secrets in the shared getbased env file, tests the connection, and restarts the gateway when safe.
OpenClawStores the Agent Access secrets and prints the OpenClaw MCP config when automatic registration is not available.
Claude CodeStores the Agent Access secrets and prepares the MCP config for Claude Code.
Claude DesktopStores the Agent Access secrets and prepares the desktop MCP config snippet.
CursorStores the Agent Access secrets and prepares the Cursor MCP config snippet.
ClineStores the Agent Access secrets and prepares the Cline MCP config snippet.
Codex CLIStores 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:
  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:
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.
  1. 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.