healow-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@healow-mcp-server search for recent lab results for patient 12345"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_STOREholds 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 directory0700. 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
uvso macOS Keychain sees the same interpreter identity and does not prompt. (Verified: writing a token in oneuv runprocess 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-mcpas a subprocess of the GUI app); if macOS ever shows an access prompt there, approve "Always Allow" once.
Related MCP server: Medplum
Requirements
Python 3.11+
uv syncEnvironment variables
Variable | Required | Description |
| yes | OAuth client id issued by healow/eCW. |
| yes | OAuth client secret (confidential client). |
| yes | Registered redirect URI. A loopback URL (e.g. |
| no | SQLite metadata DB path. Default |
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_URIis a loopback URL, the helper runs a temporary local server, captures thecodeautomatically, 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
connect_practice(name, fhir_base_url)→ returns{authorize_url, state}.Open
authorize_urlin a browser, log in, and consent.Copy the
codefrom the redirect and callcomplete_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 keychainTests 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.
Available Tools
20 toolscomplete_oauthA
Exchange an authorization code (and its state) for tokens. Returns the practice name and the patient context from the token response / id_token.
Inputs: code (required), state (required).
connect_practiceA
Begin connecting a practice. Returns an authorize_url to open in a browser and the state to track this attempt. Complete the flow with complete_oauth.
Inputs: name (required), fhir_base_url (required).
fhir_getA
Read any FHIR resource by type and id. Returns the raw resource.
Inputs: id (required), practice (required), resource (required).
fhir_searchA
Search any FHIR resource type with arbitrary query params. Returns the raw Bundle (first page; follow Bundle.link[next] for more).
Inputs: params (required), practice (required), resource (required).
get_binaryA
Fetch a Binary by id as {content_type, data_base64}.
Inputs: id (required), practice (required).
get_capability_statementB
Fetch the server CapabilityStatement ({base}/metadata).
Inputs: practice (required).
get_coverageA
Read a Coverage resource by id.
Inputs: id (required), practice (required). Returns: id, type, payor, status, +2 more
get_document_referenceA
Read a DocumentReference by id (content URLs fetchable via get_binary).
Inputs: id (required), practice (required). Returns: id, date, type, status, +2 more
get_patientB
Get the patient in the launch context for a practice.
Inputs: practice (required). Returns: id, name, gender, birthDate, +1 more
get_practitionerB
Read a Practitioner resource by id.
Inputs: id (required), practice (required). Returns: id, name, gender, resourceType
list_allergiesC
List AllergyIntolerance resources for the launch patient.
Inputs: practice (required). Returns: result
list_care_plansA
List CarePlan resources for the launch patient.
Inputs: practice (required). Returns: result
list_immunizationsB
List Immunization resources for the launch patient.
Inputs: practice (required). Returns: result
list_practicesA
List connected practices with their FHIR base URL, patient id, and when they were connected.
Inputs: no named parameters. Returns: result
list_problemsB
List problem-list Conditions for the launch patient.
Inputs: practice (required). Returns: result
search_conditionA
Search Conditions for the launch patient. Optional category (problem-list-item, health-concern, encounter-diagnosis).
Inputs: practice (required), category. Returns: result
search_encounterA
Search Encounters for the launch patient. Optional status/date filters.
Inputs: practice (required), date, status. Returns: result
search_medication_requestA
Search MedicationRequests for the launch patient. Optional status filter.
Inputs: practice (required), status. Returns: result
search_observationA
Search Observations for the launch patient by USCDI category (laboratory, vital-signs, social-history, survey, sdoh, exam).
Inputs: category (required), practice (required), code, date. Returns: result
whoamiB
Return the id_token claims for a connected practice (patient/user context).
Inputs: practice (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Most tools are clearly distinct by resource type (e.g., search_encounter vs. search_condition). The generic fhir_get/fhir_search overlap with specific wrappers, but descriptions clarify their broad vs. focused nature. A few potential confusions exist (e.g., list_allergies vs. search_condition), but overall boundaries are clear.
Tool names are all snake_case but mix verb styles: get_ (get_patient), search_ (search_encounter), list_ (list_allergies), fhir_ (fhir_get), plus standalone names (whoami, connect_practice). This inconsistent verb choice across similar operations (e.g., search_observation vs. list_immunizations) makes the pattern less predictable.
20 tools is reasonable for a FHIR server covering authentication, generic FHIR operations, and a broad set of clinical resource types. While slightly on the higher side, each tool serves a distinct resource or workflow, and the count matches the domain complexity.
The toolset covers core FHIR resources (Patient, Encounter, Observation, Condition, MedicationRequest, etc.) with both list and search capabilities. Missing common resources like DiagnosticReport or Procedure can be accessed via generic fhir_search, so agents can work around gaps. The read-only scope is consistent with the OAuth launch context.
Maintenance
Related MCP Connectors
Hosted MCP server for the Healthie EHR & telehealth API: patients, appointments, charting, tasks.
Hosted MCP server for Cliniko — patients, appointments, availability, and invoices for AI agents.
Hosted MCP server exposing US hospital procedure cost data to AI assistants
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceThis project builds a read-only MCP server. For full read, write, update, delete, and action capabilities and a simplified setup, check out our free CData MCP Server for FHIR (beta): https://www.cdata.com/download/download.aspx?sku=KIZK-V&type=betaMIT
- AlicenseNot gradedqualityBmaintenanceOfficial Medplum MCP server for healthcare automation2,806Apache 2.0

FHIRfly MCP Serverofficial
AlicenseNot gradedqualityCmaintenanceMCP server for connecting Claude Desktop to FHIRfly healthcare reference data APIs, enabling lookup of drugs, providers, clinical codes, and more.71 npmMIT- AlicenseNot gradedqualityDmaintenanceAn MCP server that brings AI-powered search and conversation to your FHIR clinical documents.1MIT