Connect Metriport to ChatGPT: Manage Patient HIE and Medical Records

If you are building healthcare applications, giving a Large Language Model (LLM) read and write access to a universal API like Metriport is a massive engineering challenge. You have to handle complex FHIR (Fast Healthcare Interoperability Resources) data models, asynchronous Health Information Exchange (HIE) queries, and strict patient demographic matching. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated Model Context Protocol (MCP) server.

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

This guide breaks down exactly how to use Truto to generate a secure MCP server for Metriport, connect it natively to ChatGPT, and execute complex HIE document retrievals and clinical data queries using natural language.

Stop writing boilerplate API integration code. Let Truto generate secure, managed MCP servers for your AI agents in seconds. :::

The Engineering Reality of the Metriport API

A custom MCP server is a self-hosted integration layer that translates an LLM's tool calls into REST API requests. While the open MCP standard provides a predictable way for models to discover tools, implementing it against a healthcare interoperability API like Metriport is painful.

If you decide to build a custom MCP server for Metriport, here are the specific integration challenges that break standard CRUD assumptions:

Asynchronous HIE Queries

Metriport queries nationwide networks (like Carequality and CommonWell) to retrieve medical records. This is not a fast database read; it takes time. When an LLM requests a patient's documents, it cannot wait synchronously for the payload. Your MCP server must expose an asynchronous flow: first, a tool to trigger the query (start_query), and second, a tool to poll for completion or retrieve webhook statuses. If you expose a blocking tool to the LLM, the request will time out, and the model will hallucinate a failure.

Strict Patient Matching

In healthcare, you cannot simply search for a patient by a loose text string. To avoid creating fragmented or duplicate electronic medical records, Metriport enforces strict demographic matching. Before executing clinical queries, your AI agent must resolve the patient using exact fields (first name, last name, date of birth, gender at birth). Your MCP schemas must enforce these required parameters strictly, otherwise Metriport will reject the request.

The FHIR Payload Paradox

Metriport returns clinical data in standardized FHIR JSON bundles. While standard, FHIR is deeply nested and verbose. An LLM attempting to parse a raw MeasureReport for care gaps or a massive Condition bundle can easily exhaust its context window. Your custom server must either provide tools that extract specific summary data (like PDF/HTML rendering endpoints) or explicitly instruct the LLM on how to navigate the pagination and structure of FHIR bundles.

Rate Limits and the 429 Reality

Metriport enforces rate limits to protect downstream HIE networks. When building an MCP server, a common mistake is hiding these limits from the caller. Truto handles this explicitly: we do not retry, throttle, or apply backoff on rate limit errors. When Metriport returns an HTTP 429, Truto passes that error directly to the caller, normalizing the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller (your AI framework) is entirely responsible for retry and backoff logic.

Generating the Metriport MCP Server

Instead of forcing your engineering team to build a custom tool server, handle FHIR schemas, and maintain OAuth sessions, Truto dynamically generates MCP tools based on Metriport's API documentation.

You can generate a secure MCP server URL in two ways: via the Truto UI, or programmatically via the API.

Method 1: Via the Truto UI

1. Navigate to the Integrated Accounts page in your Truto dashboard.
2. Select your connected Metriport account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Configure the server (e.g., restrict to read methods or apply specific tags).
6. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/abc123xyz...).

Method 2: Via the Truto API

For teams building automated onboarding flows, you can provision an MCP server programmatically. Truto will validate that the Metriport integration has documented tools, generate a secure, hashed token, and return a ready-to-use URL.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Metriport HIE Assistant",
    "config": {
      "methods": ["read", "write", "custom"]
    }
  }'

The API returns the connection string required by your AI client:

{
  "id": "mcp_8a9b0c...",
  "name": "Metriport HIE Assistant",
  "url": "https://api.truto.one/mcp/your-secure-token-hash-here",
  "config": { "methods": ["read", "write", "custom"] },
  "expires_at": null
}

Connecting the MCP Server to ChatGPT

Because the Truto MCP URL contains a cryptographic token that securely identifies the integrated Metriport account, you do not need to configure complex authentication headers on the client side. You can plug this URL directly into ChatGPT.

Method 1: Via the ChatGPT UI

1. Open ChatGPT and navigate to Settings -> Apps -> Advanced settings.
2. Enable the Developer mode toggle (MCP support is currently behind this flag).
3. Under MCP servers / Custom connectors, click Add new server.
4. Enter a descriptive name (e.g., "Metriport HIE").
5. Paste the Truto MCP URL into the Server URL field.
6. Click Save.

ChatGPT will immediately connect, perform an initialization handshake, and discover all available Metriport tools.

Method 2: Via manual configuration file (SSE Transport)

If you are using an AI agent framework (like LangChain or LangGraph) or a desktop client that supports standard MCP configuration files, you can configure the connection using the Server-Sent Events (SSE) transport protocol.

{
  "mcpServers": {
    "metriport_hie": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://api.truto.one/mcp/your-secure-token-hash-here"
      ]
    }
  }
}

Metriport Hero Tools for AI Agents

Truto automatically maps Metriport's endpoints into descriptive, callable tools for the LLM. Here are the highest-leverage tools your agent can use to interact with patient data.

Match Patient Demographics

metriport_patients_match

Before executing clinical queries, the LLM must find the exact patient record in Metriport. This tool accepts strict demographic criteria and returns the matched patient ID, ensuring you do not duplicate medical records.

"Check if we have a patient matching the name John Doe, born 1980-05-15, male, in our Metriport network. If found, give me their patient ID."

Start Document Query

metriport_documents_start_query

Triggers an asynchronous query across HIE networks (Carequality, CommonWell) to retrieve clinical documents for a specific patient. Because this is asynchronous, the LLM will receive a requestId to track the operation's progress.

"Initiate a document query across the HIE networks for patient ID 12345 to retrieve their latest medical records."

Get Medical Record Summary

metriport_patients_get_medical_record_summary

Instead of forcing the LLM to parse raw FHIR bundles, this tool generates a downloadable URL for a Medical Record Summary in PDF or HTML format. The URL is valid for 10 minutes, allowing the agent or user to immediately view the consolidated record.

"Generate an HTML medical record summary for patient ID 12345 and give me the secure download link."

List Care Gaps

metriport_care_gaps_list_for_patient

Retrieves a list of care gaps for a specific patient. This returns a FHIR Bundle detailing missing screenings, overdue medications, or unaddressed conditions, allowing the AI to act as a clinical assistant for care coordinators.

"List all identified care gaps for patient ID 12345 so we can schedule the necessary follow-up appointments."

Start Consolidated Data Query

metriport_consolidated_data_start_query

Starts a query to retrieve cached FHIR data, PDF, or HTML files for a patient. This is heavily utilized when you need structured clinical data spanning specific date ranges rather than unstructured documents.

"Start a consolidated data query for patient ID 12345 for all encounters in the year 2023. Format the result as FHIR JSON."

Get Network Query Status

metriport_network_queries_get_status

Allows the LLM to check the progress of an active network query retrieving health data from pharmacies, labs, and HIEs. It returns meta information on exactly which network sources have responded.

"Check the status of the network query with request ID abc-987 for patient 12345. Are the laboratory results back yet?"

To view the complete inventory of available Metriport tools, required parameters, and JSON schemas, visit the Metriport integration page.

Workflows in Action

Connecting tools is only half the battle. Here is how a ChatGPT agent sequences these tools to automate real-world healthcare interoperability tasks.

Workflow 1: Patient Intake and Historical Record Retrieval

When a new patient arrives, a care coordinator asks the AI agent to pull their historical records from the national HIE network.

"A new patient, Jane Smith, born 1975-10-22, female, is checking in. Find her in Metriport, initiate a document query across the HIE network, and generate a medical record summary link for the doctor to review."

How the agent executes this:

1. Calls metriport_patients_match with firstName, lastName, dob, and genderAtBirth to resolve the demographics into a Metriport patient ID.
2. Calls metriport_documents_start_query using the retrieved patient ID to trigger the asynchronous nationwide search.
3. Calls metriport_patients_get_medical_record_summary requesting a PDF conversion, returning the secure 10-minute download URL back to the user in the chat.

sequenceDiagram
    participant User as User
    participant Agent as ChatGPT Agent
    participant MCP as Truto MCP Server
    participant Metriport as Metriport API

    User->>Agent: Find Jane Smith and pull records
    Agent->>MCP: Call metriport_patients_match
    MCP->>Metriport: POST /medical/v1/patient/match
    Metriport-->>MCP: Returns patientId
    MCP-->>Agent: { patientId: "abc-123" }
    Agent->>MCP: Call metriport_documents_start_query
    MCP->>Metriport: POST /medical/v1/document/query
    Metriport-->>MCP: { status: "processing" }
    MCP-->>Agent: Query initiated
    Agent->>MCP: Call metriport_patients_get_medical_record_summary
    MCP->>Metriport: GET /medical/v1/patient/abc-123/summary
    Metriport-->>MCP: Returns PDF URL
    MCP-->>Agent: { url: "https://metriport.com/download/..." }
    Agent->>User: Found patient. Here is the medical record summary link.

Workflow 2: Clinical Care Gap Audit

A population health manager wants to ensure a specific patient is up to date on required screenings.

"I need to audit the care gaps for patient ID 98765. Pull their active care gaps and check if they are currently associated with the 'Diabetic Management' cohort."

How the agent executes this:

1. Calls metriport_care_gaps_list_for_patient with the provided patient ID, retrieving the FHIR bundle outlining missing clinical interventions.
2. Calls metriport_patients_list_cohorts to pull the active group assignments for the patient.
3. The agent parses the FHIR response, cross-references the cohort membership, and returns a plain-English summary of what the patient needs and whether they are in the correct management program.

Security and Access Control

Exposing healthcare APIs and PHI to LLMs requires strict operational boundaries. Truto provides several mechanisms to lock down your Metriport MCP servers:

• Method Filtering: Restrict an MCP server to only allow read-only operations. By configuring methods: ["read"], you guarantee the AI agent can only query patient data and cannot accidentally invoke a create or delete tool.
• Tag Filtering: Group tools by functional areas. You can generate an MCP server that only exposes tools tagged with documents or cohorts, keeping the agent strictly scoped to a specific domain.
• Expiration Timers: Use the expires_at parameter to generate ephemeral MCP servers. If you need to give an AI agent temporary access to pull a patient record, you can set the server to expire automatically, ensuring zero persistent access.
• API Token Authentication: By enabling require_api_token_auth: true, the token embedded in the URL is no longer sufficient. The MCP client must also pass a valid Truto API token in the Authorization header, enforcing a second layer of identity verification.

Moving Fast with Managed Infrastructure

Building healthcare integrations is notoriously slow. The burden of managing FHIR schemas, asynchronous HIE websockets, and exact patient-matching semantics can stall your product roadmap for months. Attempting to map all of that into an MCP server for ChatGPT compounds the difficulty.

Truto abstracts this complexity entirely. By automatically translating documented Metriport resources into standardized, executable AI tools, your engineering team skips the boilerplate. You get dynamic tool generation, secure identity resolution, and predictable execution out of the box.

Stop wrangling custom integration layers. Generate an MCP server and let your AI agents focus on coordinating care and managing data.