Agent guide

Beta — This feature is subject to change. The MCP specification and our implementation may evolve.

Flexpa enables agents and AI systems to access patient health data with consent and authorization. Try this for yourself with Claude or ChatGPT.

Patients who link their data to an agent can ask natural language questions about their health data, made possible by our 3-in-1 network of health record access:

"What are my recent claims?"
"Show me my insurance card"
"Summarize my health records"
"What medications am I currently taking?"
"Show me my recent lab results"

#MCP Server

Flexpa exposes a Model Context Protocol (MCP) server that standardizes how AI applications connect to external data sources.

Note: We also support personal use in Claude and ChatGPT. See configurations below.

#How it works

Patient authorizes access through Flexpa Consent
Your application obtains a patient access token or application access token
Configure the MCP client with the token
AI assistant can now query health data through MCP tools and resources

Endpoint

POST https://api.flexpa.com/mcp

Authentication

Authorization: Bearer <access_token>

The MCP server uses the same access tokens as the FHIR API. No additional authentication setup required. Authentication uses OAuth 2.1 PKCE flow as defined by MCP remote authentication requirements and SMART on FHIR.

#Configuration

#Claude Desktop / Claude.ai

Add Flexpa as a custom connector in Claude Desktop or Claude.ai.

Go to Settings → Custom Connectors
Click Add Custom Connector
Enter a name (e.g., "Flexpa")
Enter the remote MCP server URL: https://api.flexpa.com/mcp
Click "Connect" to authorize through Flexpa
Complete the authorization flow on the Flexpa page

Once connected, Claude will have access to your health data through MCP tools and prompts.

For team/enterprise plans: Contact your administrator to have the Flexpa MCP server added to your organization.

The custom connector uses remote authentication via OAuth. When you click "Connect", you'll be redirected to Flexpa to authorize access to your health data.

#ChatGPT

Add Flexpa using the OpenAI Apps SDK in developer mode.

Enable developer mode:

Go to Advanced settings
Toggle developer mode on

Create connector:

Go to Settings → Apps → Create
Enter connector name: "Flexpa"
Add a description explaining it provides health data access
Enter connector URL: https://api.flexpa.com/mcp
Submit the form

Use in conversation:

Click the + button near the message composer
Select More and choose Flexpa from available tools
Start asking questions about health data

Developer mode is available in beta to Pro, Plus, Business, Enterprise and Education accounts on the web. The Flexpa MCP server uses remote authentication via OAuth.

#Claude Code

Not supported for patient access tokens — Claude Code currently only works with application access tokens. Patient access token flows are not supported.

Add Flexpa as an MCP server in Claude Code using the CLI or settings file.

The --transport http flag specifies the Streamable HTTP transport.

Claude Code

claude mcp add flexpa \
  --transport http \
  https://api.flexpa.com/mcp

#Resources

MCP resources provide direct access to data via URI. Resources are read-only and return data in a format optimized for AI consumption.

Resource URI	Description
`flexpa://patient`	Simplified patient demographics
`flexpa://insurance-card`	Insurance card details (member ID, plan, payer)
`flexpa://health-summary`	Complete health data summary
`flexpa://fhir/Patient`	Raw FHIR Patient bundle
`flexpa://fhir/Coverage`	Raw FHIR Coverage bundle
`flexpa://fhir/ExplanationOfBenefit`	Raw FHIR EOB bundle (claims)

Simplified resources (flexpa://patient, flexpa://insurance-card) extract key fields from FHIR data into a flat structure that's easier for AI models to process.

Resource read

{
  "method": "resources/read",
  "params": {
    "uri": "flexpa://patient"
  }
}

#Tools

MCP tools are functions that AI assistants can invoke to retrieve data. Each tool returns structured health data that the AI can interpret and present to users.

#get_health_summary

Retrieves a comprehensive summary of all available patient health data in a single call. This tool implements functionality similar to the FHIR Patient/$everything operation, returning:

Patient demographics: Name, birth date, address, contact details
Insurance coverage: Plan information, member ID, coverage period, payer details
Claims history: Recent Explanation of Benefits (EOBs) with claim details, costs, and providers
Clinical data: Medications, lab results, and other clinical resources (when available via ONC (g)(10) or TEFCA)

This is the recommended tool for getting a complete picture of a patient's health record. Use more specific tools when you only need a subset of data.

The response is optimized for AI consumption with simplified structures and extracted key fields from FHIR resources.

{
  "name": "get_health_summary",
  "arguments": {}
}

#get_patient

Retrieves patient demographic information including name, birth date, address, and contact details.

{
  "name": "get_patient",
  "arguments": {}
}

#get_coverage

Retrieves insurance coverage details including plan information, member ID, and coverage period.

{
  "name": "get_coverage",
  "arguments": {}
}

#get_claims

Retrieves recent health insurance claims (Explanation of Benefits). Supports pagination via the limit parameter.

Parameters

limitnumber: Maximum number of claims to return (default: 10)

{
  "name": "get_claims",
  "arguments": { "limit": 5 }
}

#fhir_read

Reads any supported FHIR resource type. Constrained to CARIN Blue Button and US Core 6.1 profiles.

Parameters

resourceTypestringRequired: FHIR resource type (e.g., Patient, Coverage, ExplanationOfBenefit)

{
  "name": "fhir_read",
  "arguments": { "resourceType": "Observation" }
}

#Prompts

MCP prompts are pre-defined conversation starters that guide the AI assistant. Select a prompt to have Claude automatically fetch and explain your health data.

Prompt	Description
`summarize_health`	Get a plain-language summary of demographics, insurance, and recent claims
`explain_insurance`	Explain your insurance coverage in plain language
`healthcare_spending`	Analyze your healthcare costs and spending breakdown
`recent_claims`	Review and explain your recent healthcare claims

In Claude Desktop, prompts appear as suggestions you can select. Claude will then automatically call the appropriate tools and explain the results.

Prompt invocation

{
  "method": "prompts/get",
  "params": {
    "name": "summarize_health"
  }
}

#Testing

Use the MCP Inspector for development and debugging. The inspector lets you connect to the MCP server, list available tools and resources, and test invocations.

You'll need a valid access token from a completed Flexpa Consent authorization.

MCP Inspector

npx @modelcontextprotocol/inspector

Connect to https://api.flexpa.com/mcp and add your access token in the Authorization header.

#Transport

The MCP server uses Streamable HTTP transport. This is the modern MCP transport that supports both request-response and streaming patterns over standard HTTP.

CORS is configured to allow requests from claude.ai and chatgpt.com origins.