healow-mcp-server

An MCP server that wraps the eClinicalWorks / healow FHIR R4 API so an MCP client (e.g. Claude Desktop) can read patient clinical data from one or more practices.

Auth is SMART on FHIR — Standalone Launch, confidential symmetric client with PKCE. Each practice has its own FHIR base URL and its own OAuth endpoints; endpoints are discovered at runtime from {base}/.well-known/smart-configuration (never hardcoded) and cached per practice.

Security model

• Secrets live in the OS keychain (macOS Keychain / Windows Credential Locker / Linux Secret Service) via keyring. The SQLite store at $HEALOW_TOKEN_STORE holds only non-secret metadata (practice name, base URL, patient id, token expiry, timestamps). Long-lived refresh tokens — which are standing keys to PHI — never touch the DB file.
• Logs go only to stderr. stdout is the MCP stdio transport. Tokens, codes, and secrets are never logged.
• The SQLite file is created 0600, its directory 0700. TLS verification is always on; HTTP uses a 30s timeout with exponential backoff on 429/5xx and a single retry on 401 after a token refresh.

Keychain note: the bootstrap helper and the MCP server should both be launched via uv so macOS Keychain sees the same interpreter identity and does not prompt. (Verified: writing a token in one uv run process and reading it in another produces no prompt.) The definitive confirmation is the first keychain access under the real Claude Desktop launch (uv run --directory … healow-mcp as a subprocess of the GUI app); if macOS ever shows an access prompt there, approve "Always Allow" once.

Requirements

• Python 3.11+
• uv

uv sync

Environment variables

Variable	Required	Description
HEALOW_CLIENT_ID	yes	OAuth client id issued by healow/eCW.
HEALOW_CLIENT_SECRET	yes	OAuth client secret (confidential client).
HEALOW_REDIRECT_URI	yes	Registered redirect URI. A loopback URL (e.g. http://localhost:9999/callback) enables auto-capture during bootstrap.
HEALOW_TOKEN_STORE	no	SQLite metadata DB path. Default ~/.healow-mcp/tokens.db.

One-time OAuth bootstrap

Connecting a practice is a one-time, human-in-the-loop step. There are two equivalent paths.

A) CLI helper (recommended)

export HEALOW_CLIENT_ID=...      # or set these in your shell profile
export HEALOW_CLIENT_SECRET=...
export HEALOW_REDIRECT_URI=http://localhost:9999/callback

uv run python scripts/oauth_helper.py \
  --name "Acme Family Medicine" \
  --fhir-base-url https://fhir4.eclinicalworks.com/fhir/r4/<orgId>

The helper prints (and opens) the authorize URL. After you log in and consent:

• if HEALOW_REDIRECT_URI is a loopback URL, the helper runs a temporary local server, captures the code automatically, and finishes the exchange;
• otherwise it prompts you to paste the code (or the full redirect URL).

On success it prints the connected practice and patient id, with tokens stored in your keychain.

B) Through MCP tools

1. connect_practice(name, fhir_base_url) → returns {authorize_url, state}.
2. Open authorize_url in a browser, log in, and consent.
3. Copy the code from the redirect and call complete_oauth(code, state) → returns {practice, patient_id}.

After connecting, tokens auto-refresh: proactively when the access token has < 60s of life, and reactively on a 401.

MCP tools

Auth / admin: connect_practice, complete_oauth, list_practices, whoami, get_capability_statement.

Generic FHIR: fhir_get(practice, resource, id), fhir_search(practice, resource, params) — return raw resources / Bundles.

Typed wrappers: get_patient, search_encounter, get_coverage, get_practitioner, search_observation(category=…), search_condition(category=…), search_medication_request, get_document_reference, get_binary, list_allergies, list_immunizations, list_care_plans, list_problems.

search_observation/search_condition take a friendly USCDI category (e.g. laboratory, vital-signs, problem-list-item) which maps to the FHIR category search parameter.

Pagination: typed search_*/list_* return the first page Bundle. Follow Bundle.link (rel next) via fhir_search to page further; no auto-pagination.

Claude Desktop config

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "healow": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/healow-mcp-server", "healow-mcp"],
      "env": {
        "HEALOW_CLIENT_ID": "your-client-id",
        "HEALOW_CLIENT_SECRET": "your-client-secret",
        "HEALOW_REDIRECT_URI": "http://localhost:9999/callback"
      }
    }
  }
}

Run the one-time bootstrap (path A or B) before or after adding this entry; tokens persist in your keychain across restarts.

Development

uv run pytest        # tests use httpx MockTransport + an in-memory keychain

Tests cover SMART discovery + caching, PKCE, proactive token refresh, the 401-refresh-retry path, 429 backoff, and an example resource search.

Note on category-qualified scopes

The exact string format for the category-qualified Condition/Observation scopes differs between SMART v1 and v2 granular scopes. It is centralized in healow_mcp/scopes.py (CATEGORY_SCOPE_STYLE / _category_scope) so it is a single edit once confirmed against healow's published scope list for your registered app.