Connect Metriport to Claude: Access Consolidated Clinical Data and Gaps

If you need to connect Metriport to Claude to automate clinical document retrieval, analyze care gaps, or parse FHIR data from Health Information Exchanges (HIEs), you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and Metriport'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.

If your team uses ChatGPT, check out our guide on /connect-metriport-to-chatgpt-manage-patient-hie-and-medical-records/ or explore our broader architectural overview on /connect-metriport-to-ai-agents-automate-patient-sync-and-messaging/.

Giving a Large Language Model (LLM) read and write access to a sprawling clinical ecosystem like Metriport is an engineering challenge. You have to handle multi-step identity resolution, map massive FHIR schemas to MCP tool definitions, and deal with asynchronous HIE network queries. Every time a clinical endpoint changes, 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 Metriport, connect it natively to Claude, and execute complex healthcare data workflows using natural language.

The Engineering Reality of the Metriport 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 Metriport's APIs is complex. You are not just integrating a simple database - you are orchestrating access across Carequality, CommonWell, and heavily regulated clinical data structures.

If you decide to build a custom MCP server for Metriport, you own the entire API lifecycle. Here are the specific challenges you will face:

Asynchronous Clinical Document Queries Metriport does not pull national HIE records synchronously. When querying for clinical data or documents, the system triggers asynchronous network operations that can take minutes to complete. An LLM has no inherent concept of asynchronous polling. If you expose raw REST endpoints to Claude, it will try to read the immediate 202 Accepted response as the final clinical document. You must design an orchestration layer that guides the LLM through a specific state machine: start query, poll status with the request ID, and fetch the final URL only when the status reads as completed.

Dense and Nested FHIR Payloads Metriport standardizes data into FHIR (Fast Healthcare Interoperability Resources) bundles. Endpoints returning care gaps or suspected conditions return deeply nested JSON graphs containing MeasureReport, Patient, Observation, and MedicationRequest resources. Feeding these raw bundles directly to Claude frequently exhausts context windows and degrades reasoning quality. A well-designed MCP tool layer must slice these payloads and map them into highly specific JSON Schemas so the model knows exactly which properties hold clinical relevance.

Strict Identity Matching Constraints Before you can query a patient's consolidated data, you must resolve them to a Metriport EID (Enterprise ID). Metriport enforces strict demographic matching (exact first name, last name, date of birth, gender). LLMs notoriously hallucinate date formats (e.g., swapping MM/DD/YYYY for ISO 8601) or mistype demographic inputs. Your MCP server must inject schema-level constraints that force the LLM to format DOBs correctly and handle 404 "Patient Not Found" errors gracefully, prompting the agent to retry with corrected parameters.

Managing Webhooks vs LLM Polling Many of Metriport's bulk extraction and network query endpoints default to webhook delivery. Since an LLM operates over an ephemeral JSON-RPC session, it cannot listen for webhooks. You must configure your MCP implementation to expose the polling counterparts of these endpoints (like metriport_consolidated_data_get_query_status) and write explicit tool instructions teaching the agent to wait and retry.

Handling Rate Limits in AI Agent Workflows

When connecting AI agents to external APIs, handling rate limits is a critical architectural decision. LLMs execute loops incredibly fast, often generating multiple tool calls per second.

Truto does not retry, throttle, or apply backoff on rate limit errors. When the Metriport API returns an HTTP 429 Too Many Requests, Truto passes that exact error back to the caller. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) following the IETF specification.

The caller (your Claude client or AI framework) is fully responsible for reading these headers and implementing retry or exponential backoff logic. Do not assume the integration layer will absorb rate limit errors - if your agent loops aggressively against Metriport's endpoints, the workflow will fail unless you handle the 429 response explicitly.

Generating the Metriport MCP Server

To connect Claude to Metriport, you need to generate an MCP server URL. Truto dynamically compiles your Metriport integration configuration, resources, and documentation records into a standardized JSON-RPC 2.0 endpoint. Tools are derived dynamically - if a Metriport endpoint has a documentation record in Truto, it becomes an AI-accessible tool.

You can generate this server using either the Truto UI or the API.

Method 1: Via the Truto UI

For administrators and non-developers, the UI is the fastest path to generating a server URL.

1. Log into your Truto dashboard and navigate to the integrated account page for your Metriport connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Configure the server. You can limit access to specific methods (e.g., read only) or specific tags (e.g., clinical_data).
5. Copy the generated MCP server URL (it will look like https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the Truto API

For automated deployments and multi-tenant AI products, you can generate MCP servers programmatically. This endpoint creates a secure token stored in a distributed key-value system for fast, edge-optimized routing.

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": "Claude Metriport Server",
    "config": {
      "methods": ["read", "write", "custom"]
    }
  }'

The response returns the tokenized URL that Claude will use to execute tools.

Connecting the MCP Server to Claude

Once you have the Truto MCP URL, you need to connect it to your Claude client. You can do this via the Claude UI or manually via a configuration file.

Method 1: Via the Claude UI (Web/Desktop)

If you are using Claude's enterprise or desktop interface with custom connector support:

1. Open Claude and navigate to Settings.
2. Go to Integrations or Connectors.
3. Click Add MCP Server or Add custom connector.
4. Paste the Truto MCP URL you generated earlier and click Add.
5. Claude will automatically handshake with the server, negotiate protocol version 2024-11-05, and index all available Metriport tools.

Method 2: Via Manual Configuration (claude_desktop_config.json)

For developers running Claude Desktop locally, you can map the remote Truto server using the standard Server-Sent Events (SSE) transport provided by the official MCP CLI.

Open your claude_desktop_config.json file (typically located in ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows) and add the following configuration:

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

Restart Claude Desktop. The application will initialize the connection and dynamically load the clinical toolset.

Hero Metriport Tools for Claude

Truto exposes Metriport's endpoints as highly described JSON-RPC tools. Below are the highest-leverage operations for building clinical AI workflows.

Match Patient Demographics

Tool: metriport_patients_match

Before executing clinical workflows, the agent must resolve a patient to a Metriport ID without duplicating records. This tool accepts strict demographics (first name, last name, DOB, gender) and returns the matched entity. If no patient exists, the agent knows to halt or fall back to creation.

"Find the Metriport patient record for John Doe, born October 12, 1985, male. If you find a match, extract the patient ID for the next steps."

Trigger Asynchronous Document Query

Tool: metriport_documents_start_query

This is the entry point for pulling records from national HIEs. Instead of returning data immediately, it returns a requestId and status. The LLM uses this to understand that a background job has begun.

"Start a document query across the HIE network for patient ID 12345. Let me know what the request ID is so we can check on it later."

Evaluate Care Gaps

Tool: get_single_metriport_care_gap_by_id

Returns detailed information about a specific care gap measure report as a FHIR bundle. The LLM can parse this bundle to determine if a patient has missed preventative screenings or medication adherence milestones.

"Pull the care gap report for gap ID 9876. Analyze the FHIR bundle and tell me exactly which population criteria the patient failed to meet."

Trigger Consolidated Data Build

Tool: metriport_consolidated_data_start_query

Initiates the aggregation of all cached clinical data for a patient into a single unified format (FHIR JSON, PDF, or HTML). Like the document query, this tool returns a status and request ID for asynchronous polling.

"Generate a consolidated data summary in HTML format for patient ID 12345. Tell me when the job is started."

Update Treatment Relationship Consent

Tool: metriport_patients_update_treatment_relationship

Crucial for compliance, this tool updates whether your organization has active consent to treat the patient. Setting this to false automatically revokes HIE access and removes the patient from treatment cohorts.

"Revoke the treatment relationship consent for patient ID 12345. Ensure you confirm the status is updated to false."

List Clinical Documents

Tool: list_all_metriport_documents

Retrieves the metadata for all FHIR DocumentReference objects available for a patient. The LLM can use this to filter by date or document type before attempting to download specific files.

"List all clinical documents available for patient ID 12345 from the last 6 months. Filter the results for discharge summaries."

For the complete inventory of available Metriport endpoints, schemas, and required parameters, visit the Metriport integration page.

Workflows in Action

Giving Claude individual tools is useful, but the real power of MCP is chaining these tools together to orchestrate complex clinical workflows.

Asynchronous Clinical Document Retrieval

When a user asks Claude for a patient's historical records, the agent must navigate Metriport's asynchronous polling architecture.

"Fetch the latest clinical documents from the HIE for Jane Smith, born 1990-05-15, female. Let me know what you find."

1. metriport_patients_match: Claude first calls the match tool using "Jane", "Smith", "1990-05-15", and "F". It extracts the Metriport id from the response.
2. metriport_documents_start_query: Using the ID, Claude triggers a network query to Carequality and CommonWell, receiving a requestId.
3. metriport_documents_get_query_status: Claude understands it must poll. It calls the status endpoint with the requestId. If the status is "processing", it waits and retries.
4. list_all_metriport_documents: Once the status is complete, Claude lists the available DocumentReference objects, analyzing the metadata to summarize the findings for the user.

sequenceDiagram
    participant User
    participant Claude as "Claude Desktop"
    participant MCP as "Truto MCP Server"
    participant Metriport as "Metriport API"

    User->>Claude: "Fetch latest HIE documents for Jane Smith..."
    Claude->>MCP: Call metriport_patients_match
    MCP->>Metriport: POST /patient/match
    Metriport-->>MCP: Returns Patient ID
    MCP-->>Claude: Returns Patient ID
    
    Claude->>MCP: Call metriport_documents_start_query
    MCP->>Metriport: POST /document/query
    Metriport-->>MCP: Returns requestId (Status: Processing)
    MCP-->>Claude: Returns requestId
    
    loop Polling
        Claude->>MCP: Call metriport_documents_get_query_status
        MCP->>Metriport: GET /document/query/status
        Metriport-->>MCP: Returns Status
        MCP-->>Claude: Returns Status (Processing -> Complete)
    end
    
    Claude->>MCP: Call list_all_metriport_documents
    MCP->>Metriport: GET /documents
    Metriport-->>MCP: Returns FHIR DocumentReferences
    MCP-->>Claude: Returns FHIR DocumentReferences
    Claude-->>User: Summarizes clinical documents

Identifying and Managing Care Gaps

Clinical coordinators often need to parse complex FHIR logic to understand why a patient was flagged in a population health system.

"Find the patient record for Robert Jones (DOB 1975-08-20, Male) and check his active care gaps. Explain what he needs to do to close them."

1. metriport_patients_match: Claude resolves the demographics to Robert's Metriport ID.
2. metriport_care_gaps_list_for_patient: Claude queries the active care gaps for this specific patient ID. The API returns a list of gap summaries.
3. get_single_metriport_care_gap_by_id: For the most critical gap, Claude queries the detailed FHIR bundle. It parses the nested MeasureReport to determine the specific failure (e.g., missing a recent HbA1c test).
4. Response: Claude synthesizes the FHIR json into plain English, telling the user that Robert needs a blood test scheduled to close his diabetes care gap.

Security and Access Control

Exposing clinical infrastructure to an LLM requires strict governance. Truto's MCP server architecture handles security through server-side configurations, ensuring the LLM can never bypass its constraints.

• Method Filtering: When generating the server token, you can restrict the agent to config.methods: ["read"]. The tool generator will simply skip create, update, and delete operations, meaning Claude physically cannot modify patient records or update consent status.
• Tag Filtering: You can scope servers by functional area. By passing config.tags: ["documents"], Truto will only compile tools for document retrieval endpoints, blinding the LLM to organization management or settings endpoints.
• Extra Authentication (require_api_token_auth): By default, the cryptographically hashed MCP URL acts as the sole credential. By setting require_api_token_auth: true, the Claude client must also pass a valid Truto session token in the headers, adding a secondary identity check for zero-trust environments.
• Expiration Tracking (expires_at): You can set a strict TTL for the server. Truto uses durable state alarms and expiring key-value stores to instantly sever the connection at the exact timestamp, destroying the toolset configuration and locking the LLM out of Metriport automatically.

Move Faster with Managed MCP

Building AI agents that safely navigate asynchronous HIE queries and massive FHIR bundles requires serious engineering effort. If you build a custom MCP server for Metriport, your team is on the hook for token state management, schema mapping, and rate limit architectures.

Truto abstracts this away. By turning API documentation directly into secure, scoped MCP tools, you can give Claude access to Metriport in minutes rather than months, keeping your engineering team focused on agent logic instead of API maintenance.