Interface Tools for Clinical Datasets via MCP and FHIR

This specialized service functions as an orchestrated server layer, enabling Large Language Models (LLMs) and autonomous digital agents to interface with protected Electronic Health Record (EHR) repositories. It strictly enforces data access via SMART on FHIR compliance and leverages the Model Context Protocol (MCP) to publish its operational methods.

Envision this system as a secured nexus, providing approved AI entities with a safe toolkit to examine and synthesize patient records sourced from heterogeneous clinical data silos.

Foundational Premise

The architecture executes in three sequential phases:

1. FHIR Client Implementation (Within this package): Establishes a secure handshake with a target EHR utilizing the established SMART App Launch procedure. It systematically retrieves comprehensive patient dossiers, encompassing both formalized data elements (medications, diagnoses, laboratory results) and unstructured narrative documentation or embedded artifacts.
2. MCP Abstraction Layer (This Service): Transforms the retrieved EHR artifacts into a consumable set of programmatic interfaces exposed through the Model Context Protocol. These methods empower external computational entities (AI models) to interrogate and analyze the clinical context without requiring direct exposure to the underlying EHR infrastructure.
3. Consumer AI Entity (External Caller): An autonomous AI construct or LLM invokes the published interfaces on the MCP Service to pose inquiries regarding the patient's longitudinal history, execute targeted data retrieval operations, or implement bespoke analytical routines.

Exposed Functional Interfaces

The MCP Abstraction Layer furnishes the following mechanisms for EHR data manipulation:

• grep_record: Executes pattern matching (literal text or regular expressions) across the entire aggregated dataset (FHIR resources plus textual content extracted from notes/attachments). Optimal for keyword identification (e.g., searching for "hypoglycemia" or "insulin regimen").
• query_record: Facilitates read-only execution of standard SQL SELECT statements against the internalized structured FHIR data structures. Valuable for precise lookups based on known resource schemas (e.g., retrieving observations identified by specific LOINC codes).
• eval_record: Permits execution of arbitrary JavaScript routines directly against the consolidated dataset (FHIR resources and associated metadata). Offers maximal runtime flexibility for complex arithmetic calculations, cross-source data aggregation, or custom report generation.

This configuration guarantees that AI agents can capitalize on rich EHR data via a standardized and cryptographically sound access vector.

(Detailed developer integration instructions and operational guidance reside within the source code documentation.)

---

Operational Modalities & Data Ingestion

This utility supports several distinct pathways for acquiring and exposing EHR information via the MCP framework:

1. Self-Contained SMART on FHIR Browser Client

This repository incorporates a deployable web artifact that facilitates user-driven EHR connection via SMART on FHIR for direct data acquisition.

• Accessible Instance: A publicly provisioned instance is reachable at: https://mcp.fhir.me/ehr-connect#deliver-to-opener:$origin (The placeholder $origin necessitates substitution with the originating window's Uniform Resource Identifier).
• Provider Filtering (?brandTags): The initial selection interface can restrict displayed EHR providers using the brandTags URL query parameter. This parameter accepts a comma-separated collection of categorical tags. Only providers whose internal configuration matches all specified tags (derived from the brandFiles definitions) will be rendered. Logical operations: OR is implied by commas (,), while AND is explicitly signaled by the caret (^). AND logic overrides OR logic.
  • ?brandTags=epic,sandbox: Displays providers tagged with epic OR sandbox.
  • ?brandTags=epic^dev: Displays providers tagged with both epic AND dev.
  • ?brandTags=epic^dev,sandbox^prod: Displays providers matching (epic AND dev) OR (sandbox AND prod).
  • Absence of the parameter defaults to displaying only providers marked with the prod tag.
  • Exemplar: .../ehr-connect?brandTags=hospital^us: Shows providers tagged with both hospital AND us.
• Workflow Mechanics: Upon launch, the page prompts the user to select their healthcare system. It subsequently initiates the standard SMART App Launch sequence, redirecting the user to the EHR's proprietary authentication portal. Post-successful credential validation and consent granting, the client fetches an extensive enumeration of FHIR resources (e.g., Patient, Observations, Documents, etc.) and concurrently attempts to derive human-readable text content from any attached binary objects (such as PDFs, RTF, or HTML embedded within DocumentReference entries).
• Result Structure (ClientFullEHR): Upon completion of the data harvesting phase, the client aggregates the entirety of the retrieved information into a singular JSON structure designated ClientFullEHR. This structure comprises:
  • fhir: A map where keys denote FHIR resource classifications (e.g., "MedicationRequest") and values are arrays containing the corresponding resource instances.
  • attachments: A list of processed artifact objects, each containing supporting metadata (source resource lineage, content locator, MIME type) alongside the payload (contentBase64 for raw binary data, or contentPlaintext for extracted textual representations).
• Data Transmission: If invoked with the #deliver-to-opener:$origin fragment identifier, the client will solicit final user confirmation before transmitting the complete ClientFullEHR object back to the initiating window via the window.opener.postMessage(data, targetOrigin) mechanism.

2. Localized MCP Engine via Standard I/O (src/cli.ts)

This execution mode is optimized for environments where the MCP service must operate transiently on a local machine, frequently integrated with specialized IDE tools like Cursor or other command-line consumers.

• Dual-Phase Execution Sequence:

  1. Data Persistence to Repository: Initially, invoke the command-line executable specifying the --create-db flag alongside the --db pointer. This action initiates a temporary web listener and employs the identical SMART on FHIR acquisition logic detailed previously to secure the data. Instead of transmitting the resultant ClientFullEHR via cross-window messaging, it persists this structure into a local SQLite database file. bash # Illustrative: Obtain data and archive to a specified SQLite file bun run src/cli.ts --create-db --db ./data/user_session_01.sqlite

     The user must follow the on-screen instructions (opening a web link) to complete the EHR authentication. 2. MCP Listener Activation: After the database file is successfully materialized, re-execute the CLI, referencing only the database path. This loads the persisted data into volatile memory and subsequently activates the MCP service, configuring it to accept instructions via standard input/output streams. bash

     Illustrative: Engage the MCP server using the pre-loaded data

     bun run src/cli.ts --db ./data/user_session_01.sqlite

  2. Configuration Context (config.*.json): This operational pathway is contingent upon a configuration manifest (e.g., config.development.json), which enumerates accessible EHR providers/endpoints within its brandFiles array. Each registry entry within this collection specifies:

     • url: The network path/URI pointing to the specific provider definition artifact (e.g., static/brands/cerner-test.json).
     • tags: An array of descriptive strings (e.g., ["cerner", "staging"]) utilized for classification or access filtering.
     • vendorConfig: Contains necessary client parameters for SMART on FHIR integration, specifically the application clientId and the required authorization scopes.
  3. Consumer Software Configuration (e.g., Cursor Integration): The external MCP client must be meticulously configured to execute this specific command sequence. It is mandatory to utilize absolute, fully qualified file paths for both the execution script (src/cli.ts) and the database artifact.

  { "mcpServers": { "local-data-session": { "name": "Local EHR Snapshot", "command": "bun", // Or the absolute path to the Node.js runtime or bun executable "args": [ "/opt/smart-mcp-tools/src/cli.ts", // Absolute path to the CLI script "--db", "/opt/smart-mcp-tools/data/user_session_01.sqlite" // Absolute path to the persisted SQLite file ] } } }

3. Persistent Networked MCP Engine via Server-Sent Events (src/sse.ts / index.ts)

This deployment paradigm is designed for continuous operation, serving requests from numerous remote clients across a network infrastructure. It employs Server-Sent Events (SSE) as the designated communication fabric for the MCP data stream.

• Authorization Protocol: Client authentication adheres to the OAuth 2.1 specification, as dictated by the Model Context Protocol standard. The server exposes conventional endpoints for credential exchange (/authorize, /token, /register, etc.).
• Data Acquisition Flow: Upon the initiation of an OAuth 2.1 handshake by a client, the server autonomously manages the entire SMART on FHIR negotiation process. It retrieves the ClientFullEHR data during the authorization handshake and retains it in session memory (or a durable persistence layer) throughout the duration of the client's active network association.
• Current Status: While the underlying infrastructure is functional, the specific implementation of OAuth 2.1 client interaction defined within the MCP specification is presently subject to substantial variability among third-party clients. Consequently, validating this operational mode outside of custom-built diagnostic utilities is currently challenging. This SSE-based server configuration must be classified as experimental pending broader client adoption.