LangCare MCP FHIR Server

Enterprise-grade MCP Server for FHIR-based EMRs, designed for robust deployments in agentic AI platforms. Fully written in Go with enterprise-grade security and generic FHIR operations that work with any FHIR R4 resource type. Ships with a 40+ Clinical Skills Library — agent-agnostic workflow guides covering medication management, lab interpretation, clinical decision support, documentation, population health, and more. &# 11088; New: LangCare now supports MCP Apps — interactive clinical UIs embedded directly in the server. Learn more.

# Installation

Install via npm:

npm install -g @langcare/langcare-mcp-fhir

Or use directly without installation:

npx @langcare/langcare-mcp-fhir -config /path/to/config.yaml

# Quick Configuration

LangCare MCP FHIR connects Claude to your FHIR-based EMR system. You need a YAML configuration file pointing to your backend.

# # 1. Get a Config Template

Choose your backend:

• EPIC: config.epic.example.yaml
• Cerner: config.cerner.example.yaml
• GCP Healthcare API: config.gcp.example.yaml
• Any FHIR R4 Server: config.base.example.yaml

# # 2. Configure Claude Desktop

Add to your Claude Desktop config file (~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "langcare-mcp-fhir": {
      "command": "langcare-mcp-fhir",
      "args": ["-config", "/path/to/your/config.yaml"]
    }
  }
}

On macOS, the config is typically at:

~/Library/Application\ Support/Claude/claude_desktop_config.json

# # 3. Restart Claude Desktop

Close and reopen Claude Desktop. The FHIR tools will now be available.

Need detailed setup help? See the Local Testing Guide.

# Architecture

This MCP server acts as an intelligent proxy between AI agents and FHIR R4 servers. It exposes 4 generic FHIR operations through the Model Context Protocol (MCP), enabling AI-powered workflows for any FHIR resource type.

Key Design:

• MCP SDK: Official github.com/modelcontextprotocol/go-sdk (Anthropic/Google maintained)
• FHIR Client: Generic HTTP client working with any FHIR R4 server
• Transport: stdio and Streamable HTTP
• Backend: Proxy to existing FHIR server (no database)
• Language: 100% Go for high performance and reliability

# 4 Generic MCP Tools

All tools work with any FHIR resource type (Patient, Observation, Medication, etc.):

# # 1. fhir_read

Read a FHIR resource by type and ID.

{
  "resourceType": "Patient",
  "id": "example-123"
}

# # 2. fhir_search

Search FHIR resources with query parameters.

{
  "resourceType": "Patient",
  "queryParams": "name=John&birthdate=gt1990-01-01"
}

# # 3. fhir_create

Create a new FHIR resource.

{
  "resourceType": "Observation",
  "resource": {
    "resourceType": "Observation",
    "status": "final",
    "code": { ... },
    "subject": { "reference": "Patient/123" }
  }
}

# # 4. fhir_update

Update an existing FHIR resource.

{
  "resourceType": "Patient",
  "id": "example-123",
  "resource": {
    "resourceType": "Patient",
    "id": "example-123",
    "name": [{ "family": "Smith" }]
  }
}

# Security Architecture

LangCare MCP FHIR implements a two-layer security model for HIPAA-compliant healthcare data access:

┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│   Claude    │ Auth1   │  MCP Server  │ Auth2   │  FHIR API   │
│   Client    │────────▶│   (Go)       │────────▶│   (EMR)     │
└─────────────┘         └──────────────┘         └─────────────┘

Auth1: MCP Client Authentication (Bearer Token/API Key)
Auth2: FHIR Backend Authentication (Bearer/OAuth2/SMART on FHIR)

# # Security Features

• ✅ TLS 1.3 encryption for HTTP transport
• ✅ PHI Scrubbing in logs (enabled by default)
• ✅ HIPAA-compliant audit logging
• ✅ No persistent PHI storage (stateless proxy)
• ✅ Secrets via environment variables (never in config files)
• ✅ OAuth 2.0 with automatic token refresh
• ✅ mTLS support for service-to-service communication
• ✅ Rate limiting per client

# # Supported Authentication Methods

• Bearer Token - Simple API key authentication
• OAuth2 - Full OAuth2 flow with token refresh
• SMART on FHIR - EPIC, Cerner, and other EMR standards
• Basic Auth - Username/password authentication
• Custom - Extensible for additional auth methods

For complete security documentation, see Security Guide:

• HIPAA compliance checklist
• OAuth configuration for EPIC/Cerner/GCP
• Kubernetes security manifests
• Credential management procedures
• Audit logging implementation

# MCP Apps (Interactive UIs)

LangCare MCP FHIR ships with built-in MCP Apps — interactive, rich UI views that run directly inside MCP-capable hosts like Claude Desktop. Unlike traditional chat-based tool output, MCP Apps render full React-based interfaces with charts, tables, and interactive controls while using the same underlying FHIR tools.

How it works: Each app is a single-file HTML bundle (React + TypeScript, compiled with Vite) that gets embedded into the Go binary at compile time via go:embed. At runtime the MCP server registers each app as both an MCP Resource (text/html;profile=mcp-app) and a dedicated MCP Tool linked via _meta.ui.resourceUri. When an MCP host calls the tool, it fetches the resource and renders the UI. The app calls back into the server's generic FHIR tools (fhir_search, fhir_read, etc.) through app.callServerTool() — no LLM round-trips for data fetching.

Advantages over plain tool output:

• Rich visualization — SVG charts, color-coded cards, expandable detail panels
• Interactive controls — search fields, date range pickers, click-to-expand rows
• Deterministic data fetching — apps call FHIR tools directly, no LLM involvement in data retrieval
• Zero external dependencies — everything inlines into a single HTML file, embedded in the binary
• Works offline — no CDN, no external scripts, no network requests beyond FHIR API calls

# # Built-in Apps

| App | Tool | Description |
|- -- --|- -- -- -|- -- -- -- -- -- --|
| FHIR Explorer | fhir_explorer | Interactive FHIR resource browser. Search, read, create, and update any FHIR R4 resource type with JSON detail views. |
| Patient Chart Review | patient_chart_review | Clinical dashboard with patient demographics, active conditions, medications, vitals, labs, and vitals trend charts (BP + weight over time). |

Both apps are reference implementations demonstrating the MCP Apps pattern. See apps/README.md for architecture details and how to build new apps.

# Agent Usage

AI agents use LangCare MCP FHIR Server to help healthcare professionals access and manage patient health records through 4 FHIR tools. The server handles EMR authentication, allowing agents to focus on clinical workflows while maintaining strict privacy and accuracy standards.

Agent capabilities:

• Search, Read, Create, Update - Any FHIR R4 resource (Patient, Observation, Medication, etc.)
• Patient privacy - Use partial identifiers, confirm identity before updates
• Clinical accuracy - Verify data, use standard codes (LOINC, SNOMED, RxNorm)
• Professional communication - Structure responses with context, findings, and next steps

Common workflows:

• Patient lookup: Search by name/DOB → verify identity → read full details
• Clinical review: Retrieve labs, vitals, medications → present with reference ranges
• Documentation: Extract structured data → map to FHIR resources → confirm → create
• Updates: Verify existing resource → modify → confirm changes → update

System support:

• Works with any FHIR R4 resource type (60+ types including DocumentReference, Binary, Media)
• Automatic authentication and token refresh to EPIC, Cerner, GCP Healthcare API
• HIPAA-compliant PHI handling with audit logging
• Comprehensive OAuth2 scopes for clinical data access

📖 Complete guide: Agent Prompt Guide - System prompt, tool examples, workflows, and error handling

# Clinical Skills Library (Optional)

40+ agent-agnostic clinical workflow guides that teach AI agents how to perform complex healthcare tasks using the MCP server's 4 FHIR tools (fhir_search, fhir_read, fhir_create, fhir_update).

• Optional - The MCP server works without them
• Portable - Work with Claude, ChatGPT, Gemini, or any AI agent
• Evidence-based - Built on USPSTF, ADA, ACC/AHA, CDC, ACOG, KDIGO, and other society guidelines
• Copy-paste ready - Add a skill's SKILL.md to your agent's system prompt or custom instructions

# # Skill Categories (40 Skills)

| Category | Skills | Examples |
|- -- -- -- -- -|- -- -- -- -|- -- -- -- -- -|
| Patient Data & Summary | 5 | Demographics, clinical summary (CCD-style), problem list audit, allergy review, insurance coverage |
| Medication Management | 5 | Med reconciliation, drug interactions (CYP450), adherence (MPR/PDC), Beers Criteria, opioid risk (ORT/MME) |
| Lab & Diagnostics | 5 | Lab interpretation, critical values (CAP/CLIA), pre-op labs, diabetes panel (ADA), renal function (KDIGO) |
| Clinical Decision Support | 5 | Sepsis (qSOFA/SOFA), cardiovascular risk (ASCVD/HEART), VTE (Wells/Caprini), fall risk (Morse), pneumonia (CURB-65) |
| Care Coordination | 5 | Discharge planning (LACE), referrals, care gaps (USPSTF), transitions of care (I-PASS), follow-up tasks |
| Documentation | 5 | SOAP notes, H&P, progress notes, discharge summaries, procedure notes |
| Population Health | 5 | Panel overview, quality measures (HEDIS), chronic disease registries, immunization status (CDC), preventive care compliance |
| Specialty | 5 | Prenatal (ACOG), pediatric growth (WHO/CDC), mental health (PHQ-9/GAD-7), oncology (TNM/RECIST), chronic pain |

Full catalog with links: skills/README.md

# # How to Use Skills

1. Browse the skills/core/ directory and pick a skill
2. Copy the skill's SKILL.md content into your AI agent's system prompt or custom instructions
3. Reference files in each skill's references/ subdirectory contain detailed clinical knowledge (scoring criteria, code tables, thresholds) that can optionally be included for deeper clinical accuracy

#  Example: Add medication-reconciliation skill to your agent
skills/core/medication-management/medication-reconciliation/
├── SKILL.md              #  Copy this into agent instructions
└── references/
    ├── reconciliation-process.md   #  Joint Commission standards
    └── high-risk-medications.md    #  ISMP high-alert drug list

Integration guides: Claude | ChatGPT | Gemini

Community contributions welcome - see CONTRIBUTING.md for guidelines.

# Development & Testing

# # Build from Source

make build

# # Run Locally (stdio mode)

make run
#  or
./bin/langcare-mcp-fhir -config configs/config.local.yaml

# # Run in HTTP Mode (Streamable HTTP)

make run-http
#  or
./bin/langcare-mcp-fhir -http -port 8080 -config configs/config.yaml

Starts the server with Streamable HTTP transport on /mcp and health check on /health.

# # Run Tests

make test

# # Lint Code

make lint

# # Deploy to Fly.io (Remote Streamable HTTP)

Deploy as a remote MCP server with Streamable HTTP transport, accessible by any MCP-compatible AI agent from anywhere.

#  Install Fly CLI
brew install flyctl
fly auth login

#  Create app
fly apps create - -name langcare-mcp-dev

#  Set CONFIG_FILE in fly/fly.dev.toml [env] block for your provider (EPIC or GCP)
#  Then set secrets (EPIC example):
fly secrets set \
  EPIC_BASE_URL="https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4" \
  EPIC_CLIENT_ID="your-client-id" \
  EPIC_TOKEN_URL="https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token" \
  EPIC_PRIVATE_KEY_B64="$(base64 < keys/epic/private-key.pem)" \
  MCP_AUTH_TOKENS="your-token" \
  - -app langcare-mcp-dev

#  Deploy
fly deploy -c fly/fly.dev.toml - -app langcare-mcp-dev

#  Verify
curl https://langcare-mcp-dev.fly.dev/health

Connect any MCP client to:

URL:   https://langcare-mcp-dev.fly.dev/mcp
Auth:  Authorization: Bearer your-token

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "langcare-fhir": {
      "url": "https://langcare-mcp-dev.fly.dev/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

Supports EPIC and GCP Healthcare API providers. See fly/README.md for provider setup, secrets, and full deployment guide.

# # Local Testing with EPIC

For step-by-step instructions on setting up EPIC credentials and testing locally:

📖 Local Testing Guide

This guide covers:

• Generating RSA keys and JWKS
• Configuring EPIC credentials
• Running the server locally
• Testing with Claude Desktop
• Troubleshooting common issues

Quick credential test:

#  Test your EPIC credentials before running the server
go run test/test_epic_token.go "your-client-id" "/path/to/private-key.pem"

# Project Structure

langcare-mcp-fhir/
├── cmd/
│   └── server/
│       └── main.go                          #  Entry point
├── internal/
│   ├── apps/                                #  MCP Apps (embedded UIs)
│   │   ├── embed.go                         #  go:embed directive for HTML bundles
│   │   ├── registry.go                      #  App metadata, tool names, resource URIs
│   │   └── dist/                            #  Built HTML bundles (copied by build)
│   │       ├── fhir-explorer.html           #  FHIR Explorer single-file bundle
│   │       └── patient-chart-review.html    #  Patient Chart Review single-file bundle
│   ├── audit/
│   │   └── logger.go                        #  HIPAA audit logging
│   ├── config/
│   │   └── config.go                        #  YAML configuration loading
│   ├── fhir/
│   │   ├── client.go                        #  FHIR HTTP client interface
│   │   ├── types.go                         #  FHIR client types
│   │   └── providers/                       #  Backend implementations
│   │       ├── base.go                      #  Base HTTP provider
│   │       ├── epic.go                      #  EPIC OAuth2 provider
│   │       ├── cerner.go                    #  Cerner OAuth2 provider
│   │       └── gcp.go                       #  GCP Healthcare API provider
│   ├── mcp/
│   │   └── server.go                        #  MCP server + app registration
│   ├── middleware/
│   │   ├── auth.go                          #  MCP authentication
│   │   └── rate_limit.go                    #  Rate limiting
│   ├── tools/                               #  MCP tool implementations
│   │   ├── registry.go                      #  Tool registry
│   │   ├── fhir_read.go                     #  Read FHIR resource
│   │   ├── fhir_search.go                   #  Search FHIR resources
│   │   ├── fhir_create.go                   #  Create FHIR resource
│   │   └── fhir_update.go                   #  Update FHIR resource
│   └── transport/
│       ├── stdio.go                         #  stdio transport (Claude Desktop)
│       └── http.go                          #  Streamable HTTP transport (production)
├── apps/                                    #  MCP App source code (React + TypeScript)
│   ├── README.md                            #  App development guide
│   ├── package.json                         #  Shared dependencies (React 19, MCP Apps SDK)
│   ├── vite.config.ts                       #  Vite build config (single-file output)
│   ├── tsconfig.json                        #  TypeScript config
│   ├── fhir-explorer/                       #  FHIR Explorer app
│   │   ├── index.html
│   │   └── src/
│   │       ├── app.tsx
│   │       └── global.css
│   └── patient-chart-review/                #  Patient Chart Review app
│       ├── index.html
│       └── src/
│           ├── app.tsx
│           └── global.css
├── scripts/
│   ├── build-apps.sh                        #  Build all apps → internal/apps/dist/
│   └── create_jwks.sh                       #  Generate JWKS from public key (EPIC)
├── pkg/
│   └── types/
│       └── errors.go                        #  Custom error types
├── configs/
│   ├── config.epic.example.yaml             #  Example configuration for EPIC
│   ├── config.cerner.example.yaml           #  Example configuration for Cerner
│   ├── config.gcp.example.yaml              #  Example configuration for GCP
│   └── config.base.example.yaml             #  Example configuration for any FHIR R4 server
├── docs/
│   ├── AGENT_PROMPT.md                      #  AI agent system prompt
│   ├── EPIC-APP-SECURITY.md                 #  EPIC authentication setup
│   ├── EPIC-SCOPES.md                       #  OAuth2 scopes reference
│   ├── LOCAL-TESTING.md                     #  Local development guide
│   └── SECURITY.md                          #  Production security guide
├── test/
│   ├── README.md                            #  Test documentation
│   └── test_epic_token.go                   #  EPIC OAuth2 token tester
├── fly/
│   ├── Dockerfile                           #  Multi-stage Go build for Fly.io
│   ├── docker-entrypoint.sh                 #  Key materialization + server startup
│   ├── fly.dev.toml                         #  Fly.io dev deployment config
│   ├── config.fly.epic.yaml                 #  Fly.io EPIC provider config
│   ├── config.fly.gcp.yaml                  #  Fly.io GCP provider config
│   └── README.md                            #  Fly.io deployment guide
├── bin/                                     #  Build output (gitignored)
│   └── langcare-mcp-fhir                    #  Compiled binary
├── go.mod                                   #  Go module definition
├── go.sum                                   #  Go module checksums
├── Makefile                                 #  Build commands
└── README.md                                #  This file

Note: The following are gitignored and not committed:

• keys/ - Private keys and credentials
• config.local.*.yaml - Local configuration files
• bin/ - Compiled binaries
• .env - Environment variables
• apps/node_modules/, apps/dist/, apps/dist-tmp/ - App build artifacts

# Documentation

# # Getting Started

• 📖 Local Development & Testing Guide - Complete guide for local setup and testing
• [🚀 Installation & Configuration](# installation) - Quick setup guide above

# # Agent Integration

• 🤖 Agent Prompt Guide - Complete guide for AI agents using LangCare MCP FHIR (tool examples, workflows, best practices)

# # Security & Authentication

• 🛡️ Security Documentation - Complete security architecture and HIPAA compliance
• 🔐 EPIC Setup Guide - JWT authentication, key generation, and JWKS registration
• 📋 EPIC Scopes Reference - Complete OAuth2 scopes guide for FHIR resources
• [🔑 Authentication Methods](# supported-authentication-methods) - Supported auth methods

# # Deployment

• Fly.io Deployment Guide - Remote Streamable HTTP deployment, provider configs, secrets, Docker

# # Development & Testing

• [🧪 Testing Methods](https://github.com/langcare/langcare-mcp-fhir/blob/main/docs/LOCAL-TESTING.md# testing-with-claude-desktop) - Claude Desktop, MCP Inspector, manual testing, and automation
• [📦 Project Structure](# project-structure) - Directory layout and architecture
• [🔧 Build Commands](# development- -testing) - Development workflow

# Dependencies

• github.com/modelcontextprotocol/go-sdk - Official MCP SDK
• gopkg.in/yaml.v3 - Configuration parsing
• golang.org/x/oauth2 - OAuth2 client library
• github.com/golang-jwt/jwt/v5 - JWT signing and verification
• Go 1.25+

# HIPAA Compliance

• PHI scrubbing enabled by default
• Never logs patient identifiers
• TLS support for HTTP transport
• Proper error sanitization
• Audit logging ready
• Stateless proxy design (no persistent storage)

# Testing

# # Public Test Server

Default configuration uses HAPI FHIR public test server (https://hapi.fhir.org/baseR4) for immediate testing without setup.

# # Test Your Setup

• 📖 Local Development & Testing Guide - Complete guide for setup, testing with Claude Desktop, MCP Inspector, and automation
• 🔐 EPIC Security Setup - Detailed EPIC authentication guide
• 🛡️ Security Documentation - Production deployment and security

# Contributing

We welcome contributions from healthcare professionals, developers, and informaticists!

There are three main ways to contribute:

# # 1. Core MCP Server (Go Development)

• Bug fixes and performance improvements
• New FHIR provider implementations (AllScripts, Athenahealth, etc.)
• Security enhancements and observability features
• Testing and CI/CD improvements

# # 2. Clinical Skills (Healthcare Workflows)

• Evidence-based clinical workflows using FHIR
• Specialty-specific protocols (cardiology, oncology, etc.)
• Population health and quality measure workflows
• Clinical decision support algorithms

Skills are agent-agnostic workflow guides that work across Claude, ChatGPT, and Gemini. No coding required - just clinical expertise and FHIR knowledge!

# # 3. MCP Apps (Interactive UIs)

• New clinical or administrative UI apps
• Enhancements to existing apps (FHIR Explorer, Patient Chart Review)
• Reusable components and patterns for healthcare UIs

See apps/README.md for the development guide.

# # 4. Agent Integrations (Platform Setup)

• Setup guides for new AI platforms
• Deployment examples (Docker, Kubernetes, cloud)
• Monitoring and observability setups
• CI/CD pipelines

Get started: Read CONTRIBUTING.md for detailed guidelines, code standards, and submission process.

Recognition: Contributors are credited in README, release notes, and skill/integration author credits. Outstanding contributors may be invited as maintainers.

Questions? Open a GitHub Discussion or issue!

# Community

• GitHub Discussions - Ask questions, share ideas: https://github.com/langcare/langcare-mcp-fhir/discussions
• GitHub Issues - Report bugs, request features: https://github.com/langcare/langcare-mcp-fhir/issues
• Contributing Guide - How to contribute: https://github.com/langcare/langcare-mcp-fhir/blob/main/CONTRIBUTING.md
• Skills - Clinical workflows: https://github.com/langcare/langcare-mcp-fhir/blob/main/skills/README.md

# License

See LICENSE file.

---

Built with ❤️ by the LangCare team and contributors.

Improving healthcare through better AI infrastructure.