---
title: "Connect CharmHealth to Claude: Sync Care Plans and Diagnostic Data"
slug: connect-charmhealth-to-claude-sync-care-plans-and-diagnostic-data
date: 2026-11-16
author: Uday Gajavalli
categories: ["AI & Agents"]
excerpt: "Learn how to connect CharmHealth to Claude using a managed MCP server. Sync FHIR-compliant care plans, diagnostic data, and CCDA documents without writing code."
tldr: "A comprehensive engineering guide on exposing CharmHealth EHR APIs to Claude via MCP. We cover handling FHIR bundles, generating dynamic tools, and securing clinical data workflows."
canonical: https://truto.one/blog/connect-charmhealth-to-claude-sync-care-plans-and-diagnostic-data/
---

# Connect CharmHealth to Claude: Sync Care Plans and Diagnostic Data


If you need to connect CharmHealth to Claude to automate clinical charting, extract insights from CCDA documents, or manage patient scheduling, you need a [Model Context Protocol (MCP) server](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/). This server acts as the translation layer between Claude's tool calls and CharmHealth's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a [secure, authenticated MCP server URL](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/). If your team uses ChatGPT, check out our guide on [connecting CharmHealth to ChatGPT](https://truto.one/connect-charmhealth-to-chatgpt-access-patient-records-and-schedules/) or explore our broader architectural overview on [connecting CharmHealth to AI Agents](https://truto.one/connect-charmhealth-to-ai-agents-automate-clinical-ehr-data-flows/).

Giving a Large Language Model (LLM) read and write access to a [highly regulated Electronic Health Record (EHR) system](https://truto.one/how-to-build-hipaa-compliant-api-integrations-for-healthcare-saas-zero-data-retention-guide/) like CharmHealth is an engineering challenge. You have to manage strict API access, map complex FHIR (Fast Healthcare Interoperability Resources) schemas to MCP tool definitions, and handle high-density XML data blocks. Every time the API evolves or you need to expose a new clinical resource, you have to update your server code, redeploy, and rigorously test the integration to [avoid exposing Protected Health Information (PHI)](https://truto.one/how-to-build-hipaa-compliant-api-integrations-for-healthcare-saas-zero-data-retention-guide/) to unauthorized scopes.

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

> Want to give your AI agents secure, authenticated access to CharmHealth and 100+ other SaaS APIs? Let's talk about managed MCP architecture.
>
> [Talk to us](https://truto.one/book-a-demo/)

## The Engineering Reality of the CharmHealth API

A custom MCP server is a [self-hosted integration layer](https://truto.one/the-hands-on-guide-to-building-mcp-servers-for-ai-agents-2026/). While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against an EHR's APIs is painful. CharmHealth utilizes a FHIR V4-compliant architecture for much of its clinical data, which introduces highly nested data models that LLMs struggle to parse raw.

If you decide to [build a custom MCP server](https://truto.one/the-hands-on-guide-to-building-mcp-servers-for-ai-agents-2026/) for CharmHealth, here are the specific integration challenges you will face:

**FHIR Bundle Pagination and Nesting**
When you query CharmHealth for resources like `CarePlan` or `DiagnosticReport`, the API does not return a flat JSON array. It returns a FHIR `Bundle`. The actual data is buried inside `Bundle.entry [].resource`. When building an MCP server, dumping a raw FHIR bundle into Claude's context window wastes tokens and often causes hallucinated extractions. You have to build an abstraction layer that unwraps these bundles, processes the pagination `next` links natively, and feeds the LLM only the relevant clinical schemas.

**Handling Massive XML CCDA Exports**
CharmHealth provides a powerful bulk export tool for medical records via the HL7 CCDA format (`GET /api/ehr/v2/fhir/patients/{patient_id}/ccda`). The response is a massive XML document. If you expose this endpoint directly to an LLM, the raw XML will consume the entire context window. Your MCP server must explicitly instruct the LLM on how to parse or summarize this specific format, often requiring intermediary text extraction logic before returning the payload to Claude.

**Strict Rate Limiting Without Safety Nets**
EHR systems heavily throttle API access to ensure system stability. A major architectural gotcha is assuming your integration middleware will magically absorb rate limits. Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When an upstream API returns HTTP 429, Truto passes that error directly to the caller. Truto normalizes upstream rate limit info into standardized headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`) per the IETF spec. The caller (your AI agent application) is entirely responsible for implementing retry logic and backoff. Do not design your system assuming the MCP layer will swallow these errors.

## Generating the CharmHealth MCP Server

Instead of manually coding tool definitions for every FHIR resource, you can use Truto to dynamically generate an MCP server. Truto reads the CharmHealth integration's resource definitions and automatically builds documentation-driven tools with complete JSON Schemas.

There are two ways to create this server: via the Truto UI or programmatically via the REST API.

### Method 1: Via the Truto UI

For teams testing workflows or setting up internal tooling, the UI is the fastest path to a working MCP server.

1. Navigate to the **Integrated Accounts** page in your Truto dashboard and select your connected CharmHealth account.
2. Click the **MCP Servers** tab.
3. Click **Create MCP Server**.
4. Configure your server (select allowed methods like `read`, filter by tags like `clinical`, and set an optional expiry date).
5. Copy the generated MCP server URL (e.g., `https://api.truto.one/mcp/a1b2c3d4e5f6...`).

### Method 2: Via the Truto API

If you are building an application that provisions AI agents dynamically for your users, you should generate MCP servers programmatically. 

Make a POST request to `/integrated-account/:id/mcp` with your desired configuration:

```bash
curl -X POST https://api.truto.one/api/integrated-account/YOUR_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CharmHealth Clinical Agent",
    "config": {
      "methods": ["read"],
      "tags": ["fhir", "clinical"]
    }
  }'
```

The response returns a secure, tokenized URL backed by a database record and Edge KV store for fast routing.

```json
{
  "id": "mcp_8a9b2c",
  "name": "CharmHealth Clinical Agent",
  "config": {
    "methods": ["read"],
    "tags": ["fhir", "clinical"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}
```

## Connecting the MCP Server to Claude

Once you have your Truto MCP URL, you can plug it into Claude. Because Truto MCP servers use JSON-RPC 2.0 over standard HTTP POST requests, they are fully self-contained. The URL contains a cryptographic token that authenticates the request to the specific CharmHealth tenant.

### Method 1: Via the Claude UI

If you are using Claude Desktop for Enterprise or Team plans, adding the server takes seconds:

1. Open Claude and navigate to **Settings**.
2. Go to **Integrations** (or **Connectors** depending on your plan tier).
3. Click **Add MCP Server**.
4. Paste the Truto MCP URL you generated.
5. Click **Add**.

Claude will immediately hit the `tools/list` endpoint, discover the CharmHealth tools, and make them available in your chat context.

### Method 2: Via Manual Configuration File

If you are running Claude Desktop locally or orchestrating a custom client that relies on the `claude_desktop_config.json` file, you can map the Truto HTTP endpoint using an SSE (Server-Sent Events) adapter. 

Since standard Claude Desktop configuration expects a local script execution (via `command`), you can use the official `@modelcontextprotocol/server-sse` CLI to bridge the local stdio connection to Truto's remote URL.

Add this to your `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "charmhealth": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f67890"
      ]
    }
  }
}
```

Restart Claude Desktop. The client will establish the connection and pull down the tool definitions.

## Hero Tools for CharmHealth

Truto auto-generates tools based on the available CharmHealth API documentation. Rather than dumping raw CRUD operations on the LLM, Truto creates descriptive, snake_case tool names with highly documented JSON Schemas for both queries and bodies. 

Here are the highest-leverage tools available for CharmHealth workflows.

### list_all_charm_health_care_plans

Fetches a bundle of `CarePlan` FHIR resources. This tool automatically handles the pagination logic for the bundle, exposing `limit` and `next_cursor` parameters to the LLM. It is critical for tracking patient treatment trajectories and chronic care management.

> "List all active care plans for patient ID 98765. Limit the results to 5 and summarize the primary goals for each plan."

### get_single_charm_health_ccda_document_by_id

Exports medical records for a specific patient in HL7 CCDA format. Because CCDA is XML-heavy, this tool executes the `GET /api/ehr/v2/fhir/patients/{patient_id}/ccda` endpoint and returns the raw document text. You should prompt Claude specifically on what data points to extract from the CCDA to prevent context flooding.

> "Fetch the CCDA document for patient ID 12345. Parse the XML and extract only the active medication list and recent allergies, formatting them as a markdown table."

### list_all_charm_health_diagnostic_reports

Queries the `DiagnosticReport` FHIR endpoint. This is used to pull lab results, imaging reports, and pathology findings. The tool allows querying by patient ID, status, or category code.

> "Find the most recent diagnostic reports for patient ID 44556. Look specifically for any lipid panel results from the last 6 months."

### list_all_charm_health_appointments

Retrieves `Appointment` resources. Useful for daily schedule orchestration, patient intake prep, or finding gaps in provider schedules. The schema allows filtering by date ranges, practitioners, and appointment status.

> "Pull the appointments scheduled for Dr. Smith for tomorrow. Filter for only 'booked' or 'arrived' statuses, and list the patient IDs associated with them."

### list_all_charm_health_medication_requests

Fetches `MedicationRequest` resources, which represent prescriptions or medication orders. This tool is essential for medication reconciliation workflows or auditing prescription histories before authorizing refills.

> "List all medication requests for patient ID 99887. Identify any prescriptions marked as 'active' and flag any controlled substances."

For the complete inventory of available tools, resource schemas, and supported operations, check out the [CharmHealth integration page](https://truto.one/integrations/detail/charmhealth).

## Workflows in Action

Connecting tools to an LLM is only useful if it solves real operational problems. Here is how you can string these MCP tools together to automate complex CharmHealth workflows.

### 1. The Pre-Visit Clinical Summary

Providers spend hours reviewing charts before seeing patients. An AI agent can automate the chart prep by pulling appointments, parsing historical CCDA data, and extracting recent labs to build a concise morning briefing.

> "Look up my schedule for today. For the first patient on the list, fetch their CCDA document and recent diagnostic reports. Generate a 3-bullet clinical summary of their chronic conditions and recent abnormal labs."

**Execution Steps:**
1. **`list_all_charm_health_appointments`**: Claude calls this tool with today's date and the provider's ID to fetch the daily schedule.
2. **Extract Patient ID**: The LLM parses the first appointment record to isolate the `patient_id`.
3. **`get_single_charm_health_ccda_document_by_id`**: Claude calls this tool using the extracted patient ID. It receives the XML payload and parses out the problem list and active medications.
4. **`list_all_charm_health_diagnostic_reports`**: Claude queries recent labs for the same patient.
5. **Synthesize**: The model combines the parsed CCDA data and lab reports into a concise, readable summary for the provider.

```mermaid
sequenceDiagram
    participant User
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant Upstream as CharmHealth API

    User->>Claude: "Prep chart for first patient today"
    Claude->>MCP: Call list_all_charm_health_appointments
    MCP->>Upstream: GET /api/ehr/v2/fhir/Appointment
    Upstream-->>MCP: FHIR Bundle
    MCP-->>Claude: JSON Array (Appointments)
    Claude->>MCP: Call get_single_charm_health_ccda_document_by_id(patient_id)
    MCP->>Upstream: GET /api/ehr/v2/fhir/patients/{id}/ccda
    Upstream-->>MCP: XML Document
    MCP-->>Claude: CCDA Text
    Claude->>MCP: Call list_all_charm_health_diagnostic_reports(patient_id)
    MCP->>Upstream: GET /api/ehr/v2/fhir/DiagnosticReport
    Upstream-->>MCP: FHIR Bundle
    MCP-->>Claude: JSON Array (Labs)
    Claude-->>User: Clinical Summary Markdown
```

### 2. Chronic Care Plan and Medication Reconciliation

Care coordinators need to ensure that a patient's active care plan aligns with their current prescriptions and recent vital signs.

> "Pull the active care plans and current medication requests for patient ID 33221. Also, check their recent observations for blood pressure readings. Tell me if their hypertension care plan matches their current medication list."

**Execution Steps:**
1. **`list_all_charm_health_care_plans`**: Claude queries the care plans for the patient, noting the specific chronic conditions being tracked (e.g., Hypertension).
2. **`list_all_charm_health_medication_requests`**: Claude fetches the active prescriptions to see what the patient is currently taking (e.g., Lisinopril).
3. **`list_all_charm_health_observations`**: Claude queries the observation endpoint to extract recent systolic and diastolic blood pressure readings.
4. **Analyze**: The model cross-references the care plan goals with the active medications and recent readings, flagging any discrepancies or uncontrolled vitals for the care coordinator.

## Security and Access Control

Exposing clinical data to AI agents requires strict guardrails. Truto MCP servers provide multiple layers of configuration to restrict what an LLM can do with the CharmHealth API.

*   **Method Filtering (`config.methods`)**: You can restrict an MCP server to strictly read-only operations. By setting `methods: ["read"]`, Truto will only generate tools for `get` and `list` operations, physically preventing the LLM from creating or deleting records.
*   **Tag Filtering (`config.tags`)**: Integrations map resources to tags. By configuring `tags: ["appointments", "demographics"]`, you can isolate the AI agent to administrative data, completely blocking access to clinical schemas like `CarePlan` or `DiagnosticReport`.
*   **Extra Authentication (`require_api_token_auth`)**: By default, possession of the MCP URL grants access. By enabling `require_api_token_auth: true`, the MCP client must also pass a valid Truto API token in the `Authorization` header, enforcing a dual-authentication requirement.
*   **Automatic Expiry (`expires_at`)**: If you are provisioning temporary AI access for an automated job or a contractor, you can set an ISO timestamp. Truto will automatically clean up the database record and Edge KV entries once the token expires, instantly terminating access.

## Moving Faster with Managed Infrastructure

Building an AI agent that speaks FHIR is difficult. Maintaining the infrastructure to parse bundles, normalize IETF rate limits, and secure OAuth lifecycles is a distraction from your core product. By leveraging a managed MCP server, you turn the complexity of the CharmHealth API into a set of clean, strictly schema-typed tools that Claude understands natively. 

You dictate the access controls, and the infrastructure handles the translation layer. Build your clinical workflows, not your plumbing.
