Skip to content

Connect CharmHealth to ChatGPT: Access Patient Records and Schedules

Learn how to connect CharmHealth to ChatGPT using a generated MCP server. This step-by-step guide covers FHIR API quirks, security, and tool calling workflows.

Yuvraj Muley Yuvraj Muley · · 9 min read
Connect CharmHealth to ChatGPT: Access Patient Records and Schedules

If you want to connect CharmHealth to ChatGPT so your AI agents can automate clinical charting, pull patient vitals, retrieve HL7 CCDA documents, or manage appointments, you need a Model Context Protocol (MCP) server. This server translates ChatGPT's JSON-RPC tool calls into CharmHealth's specific FHIR R4 API requests. You can spend weeks building, hosting, and maintaining a custom MCP server, or you can use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL in seconds.

If your team uses Claude, check out our guide on connecting CharmHealth to Claude or explore our broader architectural overview on connecting CharmHealth to AI Agents.

Giving a Large Language Model (LLM) read and write access to a live Electronic Health Record (EHR) system is a massive engineering challenge. Healthcare APIs are heavily nested, rely on strict medical standards like FHIR, and require rigorous security and pagination handling.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for CharmHealth, connect it natively to ChatGPT, and execute complex clinical workflows using natural language.

The Engineering Reality of the CharmHealth API

Building a custom MCP server means owning the entire API lifecycle. While the open MCP standard provides a predictable way for ChatGPT to discover tools, implementing it against CharmHealth's EHR architecture is exceptionally painful for standard CRUD developers. Here is what breaks standard API assumptions when working with CharmHealth:

FHIR Bundles and Pagination Complexity

Unlike a typical REST API that returns a simple array of objects, CharmHealth implements the FHIR R4 standard. When you call a list endpoint (e.g., GET /api/ehr/v2/fhir/Patient), the API does not return an array of patients. It returns a FHIR Bundle resource. The actual patient data is deeply nested inside Bundle.entry [].resource. Furthermore, pagination relies on interpreting the Bundle.link array to find the next relation URL, while tracking Bundle.total. If you build a custom MCP server, your code must intercept these bundles, extract the relevant schemas, and explicitly instruct the LLM on how to pass the next URL or cursor back to the server to traverse pages.

Asynchronous Bulk Exports and System Scopes

Certain operations in CharmHealth, particularly population health data extraction, cannot be handled synchronously. Initiating a bulk export (e.g., GET /api/ehr/v2/fhir/Group/{group_id}/$export) requires a backend system scope connection. The API responds immediately with a Content-Location header and a job ID, not data. Your MCP server must expose tools to initiate the job, poll the $export-poll-status endpoint for a 202 Accepted until it receives a 200 OK, and then parse the resulting output file URLs. Asking an LLM to navigate this stateful, async polling loop requires highly specific tool design.

Unstructured CCDA XML vs. Structured FHIR

While most of CharmHealth's endpoints return structured FHIR JSON, fetching complete medical records often relies on the Consolidated Clinical Document Architecture (CCDA). A call to fetch a CCDA document returns raw HL7 XML text. Your MCP server must properly route this XML payload to the LLM without breaking JSON serialization, and the LLM must be prompted effectively to parse clinical XML rather than expecting a flat JSON object.

Rate Limits and Header Normalization

Healthcare APIs enforce strict concurrency and request limits. Truto does not retry, throttle, or apply backoff on rate limit errors. When the CharmHealth API returns an HTTP 429 (Too Many Requests), Truto passes that error directly to the caller (ChatGPT). However, Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller or the LLM orchestration layer is entirely responsible for reading these headers and executing retry/backoff logic. Do not expect the MCP server to magically absorb rate limits.

Step-by-Step Guide: Connect CharmHealth to ChatGPT

Here is exactly how to generate a CharmHealth MCP server using Truto and plug it into ChatGPT.

Step 1: Connect CharmHealth to Truto

Before generating tools, you need an authenticated connection to CharmHealth.

  1. In the Truto dashboard, navigate to Integrated Accounts -> New Integrated Account.
  2. Select CharmHealth and follow the OAuth or API Key setup flow.
  3. Once connected, note the integrated_account_id. Truto will handle the token lifecycle, ensuring ChatGPT never fails due to an expired access token.

Step 2: Generate the CharmHealth MCP Server

An MCP server in Truto is scoped to a single integrated account. This creates a secure boundary, ensuring the LLM only interacts with the exact tenant you authorize. You can generate the server via the UI or the API.

Option A: Via the Truto UI

  1. Navigate to the integrated account page for your CharmHealth connection.
  2. Click the MCP Servers tab.
  3. Click Create MCP Server.
  4. Select your desired configuration (e.g., restrict to read methods, or tag filter for patients and appointments).
  5. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4...).

Option B: Via the Truto API For programmatic deployment, create the server using the Truto REST API. This is ideal if you are dynamically provisioning AI agents for multiple clinics.

curl -X POST https://api.truto.one/integrated-account/<INTEGRATED_ACCOUNT_ID>/mcp \
  -H "Authorization: Bearer <TRUTO_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CharmHealth ChatGPT Integration",
    "config": {
      "methods": ["read", "write", "custom"],
      "tags": ["patients", "appointments", "clinical"]
    }
  }'

The API returns a payload containing the url. Treat this URL as a secret—it contains the cryptographic hash that authenticates the JSON-RPC tunnel.

Step 3: Connect the MCP Server to ChatGPT

Now, register the server with ChatGPT so it can discover the FHIR tools.

Option A: Via the ChatGPT UI

  1. Open ChatGPT and navigate to Settings -> Apps -> Advanced settings.
  2. Enable Developer mode (MCP support requires a Pro, Plus, Business, Enterprise, or Education seat with this enabled).
  3. Under MCP servers / Custom connectors, click to add a new server.
  4. Name it (e.g., "CharmHealth Provider Assistant").
  5. Paste the Truto MCP Server URL.
  6. Click Save. ChatGPT will perform an MCP handshake, run tools/list, and immediately equip your agent with CharmHealth capabilities.

Option B: Via Manual Config File (Local/Desktop) If you are running a custom AI application or using an MCP-compatible desktop client (like Claude Desktop or Cursor, which follow the same spec), you can map the server using the standard MCP SSE transport command.

{
  "mcpServers": {
    "charmhealth-prod": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/<YOUR_TRUTO_TOKEN>"
      ]
    }
  }
}

Restart your client, and the tools will auto-register.

Security and Access Control

Handing an LLM access to Patient Health Information (PHI) requires extreme caution. Truto MCP servers provide four mechanical layers of access control configured during token generation:

  • Method Filtering (methods): Limit the LLM's blast radius. Passing ["read"] ensures ChatGPT can only call GET and list operations, physically preventing it from creating or altering patient records.
  • Tag Filtering (tags): Restrict the API surface by resource tags. Passing ["appointments"] hides all clinical lab, condition, and medication tools, restricting the agent entirely to scheduling context.
  • Extra Authentication (require_api_token_auth): When set to true, possessing the MCP URL is not enough. The client must also pass a valid Truto API token in the Authorization: Bearer header, enforcing strict identity checks for backend agents.
  • TTL Expiration (expires_at): Auto-expire the MCP server at a specific ISO datetime. Perfect for granting an agent temporary, 1-hour access to pull a daily report before the token self-destructs.

Hero Tools for CharmHealth

When ChatGPT connects, Truto dynamically generates tool definitions based on CharmHealth's documentation. Here are the most critical tools for clinical and operational AI workflows.

List All Patients

Tool Name: list_all_charm_health_patients

Fetches a FHIR Bundle of Patient resources. This is the entry point for almost all clinical workflows, allowing the agent to search for patients by demographic query parameters and retrieve the crucial FHIR resource IDs needed for subsequent calls.

"Find the patient record for John Doe born in 1985 and return his FHIR resource ID."

Get Single Appointment by ID

Tool Name: get_single_charm_health_appointment_by_id

Fetches a specific Appointment resource using its FHIR ID. This provides the agent with scheduling context, including the participant lists (practitioner and patient), status, start/end times, and appointment type.

"Get the details for appointment ID 847293 and tell me which provider the patient is scheduled to see."

List All Observations

Tool Name: list_all_charm_health_observations

Retrieves a Bundle of Observation resources, which encompass vital signs, lab results, and clinical measurements. Agents use this to track patient metrics over time or flag abnormal results for a physician.

"List the most recent blood pressure and heart rate observations for patient ID 10492."

Get Single CCDA Document

Tool Name: get_single_charm_health_ccda_document_by_id

Exports the complete medical records of a patient in HL7 CCDA XML format. Because LLMs are exceptionally good at parsing XML, passing this document to ChatGPT allows it to instantly summarize a patient's entire medical history, allergies, and ongoing treatments.

"Fetch the full CCDA XML document for patient ID 44921, read through it, and give me a one-paragraph clinical summary of their active problems."

Start Bulk Export

Tool Name: charm_health_bulk_exports_start

Initiates an asynchronous bulk export job for a specified group of patients (Group/{group_id}/$export). This returns a job ID that the agent must use to poll for the completed data files. Highly useful for end-of-day analytics reporting.

"Start a bulk export for patient group ID 99201 and give me the job ID so I can check on it later."

List All Medication Requests

Tool Name: list_all_charm_health_medication_requests

Fetches a Bundle of MedicationRequest resources. Essential for medication reconciliation, allowing the agent to view active prescriptions, dosages, and refill statuses for a specific patient.

"List all active medication requests for patient ID 38210 and check if any are marked as PRN (as needed)."

To view the complete inventory of available endpoints, schemas, and custom methods, visit the CharmHealth Integration Page.

Workflows in Action

Here is how an LLM utilizes these tools in sequence to automate real-world healthcare tasks.

Workflow 1: The Pre-Encounter Clinical Briefing

A physician asks ChatGPT to prepare them for an upcoming appointment by summarizing the patient's recent vitals and full medical history.

"Look up my 2:00 PM appointment today (Appointment ID 99281). Find out who the patient is, check their latest vital sign observations, and then pull their full CCDA document to give me a bulleted summary of their active conditions and medications before I walk in the room."

Execution Steps:

  1. ChatGPT calls get_single_charm_health_appointment_by_id using ID 99281 to extract the Patient reference ID.
  2. ChatGPT calls list_all_charm_health_observations filtered by that Patient ID to grab the most recent vitals (blood pressure, weight, etc.).
  3. ChatGPT calls get_single_charm_health_ccda_document_by_id to download the comprehensive XML medical record.
  4. The LLM parses the XML, synthesizes the vitals, and outputs a concise pre-encounter brief for the doctor.
sequenceDiagram
    participant User as Physician
    participant ChatGPT as ChatGPT
    participant Truto as Truto MCP
    participant CharmHealth as CharmHealth API

    User->>ChatGPT: "Summarize patient for Appt 99281"
    ChatGPT->>Truto: call get_single_charm_health_appointment_by_id
    Truto->>CharmHealth: GET /api/ehr/v2/fhir/Appointment/99281
    CharmHealth-->>Truto: JSON (Patient ID: 5542)
    Truto-->>ChatGPT: Tool Result
    
    ChatGPT->>Truto: call list_all_charm_health_observations<br>(patient=5542)
    Truto->>CharmHealth: GET /api/ehr/v2/fhir/Observation?patient=5542
    CharmHealth-->>Truto: FHIR Bundle (Vitals)
    Truto-->>ChatGPT: Tool Result

    ChatGPT->>Truto: call get_single_charm_health_ccda_document_by_id<br>(id=5542)
    Truto->>CharmHealth: GET /api/ehr/v2/fhir/patients/5542/ccda
    CharmHealth-->>Truto: HL7 CCDA XML
    Truto-->>ChatGPT: Tool Result

    ChatGPT-->>User: Clinical summary delivered

Workflow 2: Asynchronous Population Health Export

A clinic administrator needs to trigger a nightly backup of a specific patient cohort and check its status.

"Start a bulk data export for our high-risk diabetic patient group (Group ID 400). Let me know the Job ID, and check if it's finished yet."

Execution Steps:

  1. ChatGPT calls charm_health_bulk_exports_start with the group_id 400.
  2. The tool returns a 202 Accepted status along with the _jobid parsed from the headers.
  3. ChatGPT immediately calls get_single_charm_health_bulk_export_by_id using that job ID to poll the status.
  4. If it receives a 202, it informs the administrator that the job is processing. If it receives a 200, it outputs the download URLs for the NDJSON data files.

Strategic Wrap-Up

Connecting CharmHealth to ChatGPT via a Model Context Protocol server transforms a static EHR into an active, conversational clinical assistant. However, handling FHIR Bundles, HL7 XML payloads, and asynchronous polling endpoints is a massive engineering tax for internal teams.

By using Truto's dynamically generated MCP servers, you offload the infrastructure, token lifecycle management, and tool schema generation. You define the security boundaries, and Truto ensures the LLM has exactly the context it needs to orchestrate CharmHealth data reliably.

FAQ

How does the CharmHealth MCP server handle API rate limits?
Truto does not retry or absorb rate limits. If CharmHealth returns an HTTP 429, Truto passes the error to ChatGPT along with IETF standard headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller is responsible for implementing backoff logic.
Can I prevent ChatGPT from editing patient records in CharmHealth?
Yes. When generating the MCP server in Truto, you can pass `methods: ["read"]` in the configuration. This strictly limits the LLM to GET and list operations, physically blocking it from writing data.
How does ChatGPT handle CharmHealth FHIR Bundles?
CharmHealth list endpoints return FHIR Bundles. The MCP server automatically provides the JSON schema to ChatGPT, which allows the LLM to parse the `Bundle.entry` array and utilize `Bundle.next` cursors for pagination.

More from our Blog