Healthbankone

Health Bank One — pull verified records via MCP

Status: live. Bootstrap Developer Program onboarded 2026-06-10.

MCP endpoint: https://mcp.app.healthbankone.com/mcp

Self-access auth: OAuth via browser/QR code — no client_secret needed for your own records. Claude Code: add to .mcp.json and run /mcp to authorize. Multi-patient (commercial) auth uses Open Dynamic Client Registration (RFC 7591).

HBO sits in our health-data source matrix as the OAuth-pulled, identity-verified equivalent of:

• HealthEx (token-pulled, no per-consumer consent — see healthex-export-redacted)
• Fasten Connect (webhook-pushed, TEFCA-verified — see fasten-connect)

What HBO gives us that HealthEx and Fasten don't

• Digital Identity verification baked in. IAL2 / AAL2 / PSD2-grade. Once a consumer authorizes HealthClaw, we get identity attributes alongside the clinical bundle — no separate CLEAR / ID.me step.
• Paper-record retrieval. HBO's pipeline includes mail-based requests for records that aren't yet digital. Useful for older patients with significant pre-2015 history.
• Writebacks. The Engagement service exposes authorized writebacks; HealthClaw can publish curatr fixes or annotated documents back to the consumer's HBO account.
• Insurance Context. Verified payer details — possibly the strongest case for HBO over the other two sources.

Setup

1. Self-access (Bootstrap — your own records)

Claude Code — add to project .mcp.json (already done in this repo):

"healthbankone": {
  "type": "http",
  "url": "https://mcp.app.healthbankone.com/mcp"
}

Then in a new session run /mcp → browser opens with QR code → scan with the Health Bank One digital ID app → approve → connected.

Claude Desktop — + → Connectors → Manage Connectors → Add custom connector → enter https://mcp.app.healthbankone.com/mcp → Connect → scan QR.

Script pull (for export → redact → ingest pipeline):

export HBO_MCP_URL=https://mcp.app.healthbankone.com/mcp
# Authorize once (opens browser + QR):
python scripts/healthbankone_oauth.py authorize --tenant-id my-tenant
# Then pull + redact + ingest:
python scripts/export_healthbankone_mcp.py --tenant-id my-tenant --discover

2. Multi-patient access (Commercial license required)

Uses Open Dynamic Client Registration (RFC 7591) to obtain client_id + client_secret. Then standard authorization-code + PKCE per patient. Contact developer@healthbankone.com to start a commercial conversation.

For the HealthClaw pipeline:

1. Register via DCR at the HBO registration endpoint (URL TBD)
2. Store HBO_CLIENT_ID, HBO_CLIENT_SECRET on Railway HealthClawGuardrails service
3. python scripts/healthbankone_oauth.py authorize --tenant-id <patient-tenant> — opens authorize URL; callback at https://app.healthclaw.io/hbo/callback
4. Tokens cached in ~/.healthclaw/hbo_tokens.json (local) or Redis (Railway)

3. Pull the records (script pipeline)

python scripts/export_healthbankone_mcp.py \
  --tenant-id my-tenant \
  --output ~/.healthclaw/exports/hbo-$(date +%Y-%m-%d).json

What the script does:

1. Loads access token from cache (~/.healthclaw/hbo_tokens.json); refreshes if expired
2. Opens MCP Streamable HTTP session to https://mcp.app.healthbankone.com/mcp with Authorization: Bearer <token>
3. --discover mode: calls tools/list, invokes every read-safe tool (filters on readOnlyHint annotation + name heuristics)
4. Redacts PHI in-process via scripts/healthclaw_redact.py — raw response never touches disk
5. Writes the redacted snapshot to disk

4. Ingest into HealthClaw

python scripts/import_healthex.py \
  --bundle-file ~/.healthclaw/exports/hbo-2026-06-04.json \
  --tenant-id my-tenant \
  --step-up-secret "$STEP_UP_SECRET"

Note: import_healthex.py expects a FHIR R4 transaction Bundle ({"resourceType":"Bundle","type":"transaction","entry":[...]}). The HBO snapshot format ({"records":{...},"_meta":{...}}) is not a FHIR Bundle — a conversion step is required. Until a convert_hbo.py script exists, use the HBO data directly via MCP tool calls in Claude Code / Claude Desktop rather than the ingest pipeline.

OpenClaw slash commands

(Implemented in openclaw/bot.py and scripts/bot_commands.py.)

Environment variables

SHARP-on-MCP compatibility check

If HBO's MCP server advertises SHARP (capabilities.experimental.fhir_context_required) or the PromptOpinion FHIR Extension, HealthClaw can also act as a forwarding layer — an MCP client that pulls from HBO using SHARP headers on every call instead of pre-pulling a snapshot. This eliminates the export-to-disk step entirely and matches the pattern PromptOpinion uses with us today. Ask on the call whether they advertise either spec. If yes, we can offer to demo HealthClaw + HBO as a SHARP-compliant pair.

Tool catalog (confirmed 2026-06-10 via live call)

14 tools confirmed live. All paginated tools use page (1-indexed int, default 1) and return <pagination> with has_more + next_page.

Data format notes (from live calls)

• RAG architecture: tools like get_conditions, get_encounters etc. return semantically-retrieved excerpts from indexed PDF documents, not parsed FHIR JSON. Expect rich narrative clinical text alongside structured rows.
• Document-centric: list_patient_documents returns the indexed source PDFs. Each retrieved document has a UUID. Multiple tool calls may return the same document UUID when that document contains the relevant data.
• Pagination: all get_* tools support pagination; list_patient_documents does not. For complete records, page until has_more=false.
• XML demographics: get_patient_basic_info returns XML (not JSON). Parse accordingly.
• FHIR codes included: lab results include LOINC; meds include RxNorm + NDC; conditions include SNOMED CT + ICD-10-CM + IMO. Full terminological richness.

Comparison to existing skills