Connect Healthie to Claude: Manage Care Plans and Patient Records

If your team needs to connect Healthie to Claude to automate care plan generation, lab order tracking, or patient charting workflows, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's JSON-RPC tool calls and Healthie's complex GraphQL and REST architecture. 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. If your team uses ChatGPT, check out our guide on connecting Healthie to ChatGPT or explore our broader architectural overview on connecting Healthie to AI Agents.

Giving a Large Language Model (LLM) read and write access to a specialized Electronic Health Record (EHR) system like Healthie is a massive engineering challenge. You have to handle API token lifecycles, translate massive clinical JSON schemas into valid MCP tool descriptions, and navigate strict API quotas and complexity caps. Every time Healthie updates a clinical endpoint or deprecates a GraphQL resource, you have to update your server code, redeploy, and test the integration.

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

The Engineering Reality of the Healthie API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against specialized healthcare B2B APIs is painful. Healthie is built to manage everything from highly customized charting forms to complex billing sequences and telehealth sessions. Its API reflects that deep domain complexity.

If you decide to build a custom Healthie MCP server, here are the specific integration challenges you will face:

GraphQL Complexity Caps Healthie relies heavily on GraphQL for its data layer. Unlike REST, where you fetch a fixed payload, GraphQL allows you to query nested relationships. To prevent abuse, Healthie enforces a strict 2000-point complexity cap on queries. For example, querying an appointment and requesting its associated Zoom cloud recording URLs or dial-in HTML can cost hundreds of points per query. If you give an LLM raw GraphQL access, it will inevitably hallucinate heavily nested queries and immediately trigger complexity limit errors. A managed MCP server abstracts these queries into REST-like RPC boundaries (e.g., get_single_healthie_appointment_by_id) that omit structurally expensive fields by default, ensuring the LLM never blows past the quota.

Nested Charting and Form Answer Groups In Healthie, patient charts are not flat text fields. They are structured as FormAnswerGroups, which contain individual FormAnswers, which belong to CustomModuleForms. If you want Claude to write a charting note addendum, it cannot just push a string to a patient ID. It must construct a specific mutation linking the addendum to the exact charting note ID (create_a_healthie_addendum). An LLM has no inherent knowledge of this relational structure. The MCP server must strictly define these schemas and enforce required ID fields to guide the model.

Handling Rate Limits in Tool-Calling Loops LLMs can execute tight loops of tool calls, especially when iterating over paginated lists of patients or appointments. When hitting Healthie's rate limits, Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream API returns an HTTP 429, Truto passes that error directly to the caller. However, Truto normalizes Healthie's rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (your orchestration layer or Claude) is entirely responsible for interpreting these headers and executing backoff logic.

Creating the Healthie MCP Server

Truto dynamically generates an MCP server for your connected Healthie account. This server derives its tool definitions directly from Healthie's API schemas and documentation.

You can create the MCP server in two ways: via the Truto UI for rapid prototyping, or via the API for programmatic, automated deployment.

Method 1: Via the Truto UI

For teams who want to quickly connect Claude to Healthie without writing deployment scripts, the UI is the fastest path.

1. Log into your Truto dashboard and navigate to the Integrated Accounts page.
2. Select your connected Healthie account.
3. Click on the MCP Servers tab.
4. Click Create MCP Server.
5. Configure your server settings (assign a name, select allowed methods like read or write, and set an expiration date if needed).
6. Copy the generated MCP Server URL (e.g., https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Via the Truto API

For production workflows, you should generate MCP servers programmatically. This is particularly useful if you are building an AI product and need to spin up isolated MCP servers for individual tenants.

Make an authenticated POST request to /integrated-account/:id/mcp.

const response = await fetch('https://api.truto.one/integrated-account/YOUR_HEALTHIE_ACCOUNT_ID/mcp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TRUTO_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Claude Healthie Assistant",
    config: {
      methods: ["read", "write", "custom"]
    }
  })
});
 
const mcpServer = await response.json();
console.log(mcpServer.url); // https://api.truto.one/mcp/a1b2c3d4...

The returned URL is a fully self-contained JSON-RPC 2.0 endpoint. The cryptographic token in the URL path authenticates the request and scopes it strictly to the specific Healthie integrated account.

Connecting the MCP Server to Claude

Once you have your Truto MCP Server URL, you must connect it to Claude. You can do this through the Claude Desktop UI or by manually editing the configuration file.

Method 1: Via the Claude UI

1. Open the Claude Desktop application.
2. Navigate to Settings -> Integrations -> Add MCP Server.
3. Paste the Truto MCP Server URL into the configuration field.
4. Click Add.

Claude will immediately perform an MCP initialization handshake, discover the Healthie tools, and make them available in your chat context.

Method 2: Via the Manual Configuration File

If you prefer to manage your environment programmatically, you can add the server directly to Claude's configuration file using the Server-Sent Events (SSE) transport protocol. Truto's MCP servers communicate over standard HTTP POST, but the official MCP CLI proxy can route this for local clients.

Edit your claude_desktop_config.json file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Restart Claude Desktop. The application will launch the SSE proxy, connect to Truto, and pull the Healthie tool schemas.

Hero Tools for Healthie

Truto provides a massive inventory of Healthie tools. Below are the highest-leverage "hero tools" that enable the most powerful clinical and administrative AI workflows.

list_all_healthie_appointments

Fetches a paginated collection of appointments. This tool is essential for calendar management, daily schedule generation, and identifying which patients require chart reviews today.

"List all my appointments scheduled for today. Show me the patient IDs and the appointment types."

list_all_healthie_users

Retrieves patient records (users). This is the foundational tool for any patient-specific workflow, as it provides the core user_id required for charting, lab orders, and care plans.

"Find the patient record for Jane Smith and retrieve her Healthie user ID."

list_all_healthie_care_plans

Fetches paginated care plan collections. Care plans in Healthie represent long-term protocols assigned to patients. This tool allows Claude to audit a patient's active regimens.

"Retrieve the active care plans for patient ID 12345. Summarize their current dietary recommendations."

list_all_healthie_chart_notes

Loads all charting notes accessible by the current provider. This gives the AI agent access to historical clinical data, which is critical for summarizing patient history before a consultation.

"Pull the 5 most recent charting notes for patient ID 12345 and summarize their progress over the last month."

create_a_healthie_lab_order

Creates a new lab order for a patient. This write operation allows the AI to automatically queue up diagnostic requests based on clinical notes or consultation summaries.

"Create a new lab order for a Comprehensive Metabolic Panel for patient ID 12345, setting the priority to high."

create_a_healthie_care_alert

Creates a new Care Alert for a patient. Care Alerts flag critical information (like allergies or compliance risks) directly on the patient's profile.

"Add a care alert for patient ID 12345 stating that they have reported a severe allergy to penicillin."

For the complete inventory of tools, including full JSON Schema definitions for every query and body parameter, view the Healthie integration page.

Workflows in Action

With Healthie connected to Claude, you can string these tools together to execute multi-step clinical and administrative operations autonomously.

Workflow 1: Pre-Appointment Chart Review

Preparing for a day of consultations requires providers to manually synthesize past notes, check active care plans, and review recent alerts. Claude can automate this entirely.

"I am seeing patient Jane Smith today. Please retrieve her patient record, pull her three most recent charting notes, and summarize her active care plans so I can prepare for the consultation."

Execution Steps:

1. list_all_healthie_users - Claude searches for "Jane Smith" to retrieve her unique patient ID.
2. list_all_healthie_chart_notes - Using the ID, Claude fetches her recent charting history.
3. list_all_healthie_care_plans - Claude retrieves her active care plan protocols.
4. The model synthesizes the raw API responses into a clean, human-readable clinical briefing.

sequenceDiagram
    participant Claude as Claude Desktop
    participant TrutoMCP as Truto MCP Server
    participant HealthieAPI as Healthie API

    Claude->>TrutoMCP: Call list_all_healthie_users (name: "Jane Smith")
    TrutoMCP->>HealthieAPI: GraphQL query (Users)
    HealthieAPI-->>TrutoMCP: Patient ID: 88472
    TrutoMCP-->>Claude: Patient record JSON

    Claude->>TrutoMCP: Call list_all_healthie_chart_notes (patient_id: 88472)
    TrutoMCP->>HealthieAPI: GraphQL query (ChartNotes)
    HealthieAPI-->>TrutoMCP: 3 recent notes
    TrutoMCP-->>Claude: Charting notes JSON

    Claude->>TrutoMCP: Call list_all_healthie_care_plans (patient_id: 88472)
    TrutoMCP->>HealthieAPI: GraphQL query (CarePlans)
    HealthieAPI-->>TrutoMCP: Active care plan data
    TrutoMCP-->>Claude: Care plans JSON

Workflow 2: Post-Consultation Lab Orders & Alerts

After a consultation, providers often dictate notes that require administrative follow-up. Claude can parse a dictated summary and immediately execute the necessary API writes.

"Based on my consultation with John Doe, his blood pressure is elevated. Flag this by creating a high-priority care alert on his profile, and then create a lab order for a full lipid panel."

Execution Steps:

1. list_all_healthie_users - Claude resolves "John Doe" to a specific patient ID.
2. create_a_healthie_care_alert - Claude constructs the JSON body to create the care alert with the specified clinical flag.
3. create_a_healthie_lab_order - Claude executes the mutation to generate the diagnostic request for the lipid panel.
4. Claude confirms to the user that the alert is active and the lab order is queued.

Security and Access Control

Giving an AI agent access to an EHR system requires strict governance. Truto MCP servers are secure by default, offering multiple layers of access control configured at the server generation level:

• Method Filtering (config.methods): You can restrict the MCP server to specific operation types. Setting methods: ["read"] ensures the server will only generate tools for get and list operations. Claude will physically not have the tools to execute create, update, or delete requests.
• Tag Filtering (config.tags): You can scope the server to specific functional areas. For example, setting tags: ["clinical"] will only expose resources tagged as clinical, hiding billing or scheduling endpoints from the AI.
• API Token Authentication (require_api_token_auth): By default, possessing the MCP URL grants access. By setting this flag to true, callers must also provide a valid Truto API token in the Authorization header, adding a strict secondary layer of security.
• Automatic Expiration (expires_at): You can set a TTL (Time-to-Live) via a valid ISO datetime. Once the timestamp passes, Truto automatically destroys the MCP token in its key-value storage, instantly revoking the AI's access to the Healthie integration.

Rethinking Clinical Automation

Connecting Healthie to Claude via a managed MCP server transforms LLMs from passive text generators into active clinical assistants. By relying on dynamically generated, documentation-driven tools, you eliminate the overhead of manually coding GraphQL wrappers, handling schema drift, and fighting complexity limits.

Your engineers can stop building bespoke integration endpoints for AI features and start focusing on core product workflows. Truto handles the protocol translation, normalizes the rate limit headers, and executes the proxy requests—giving Claude immediate, secure access to your Healthie ecosystem.