FHIR MCP Server for Interoperable Clinical Data

Overview

The FHIR MCP (Model Context Protocol) Server provides a bridge between clinical data stored in FHIR servers and modern search, analytics, and AI workflows. It exposes a consistent API that supports natural language and programmatic search over patient and clinical resources, plus facilities for generating context payloads that are consumable by large language models (LLMs) and other AI tools. The result is faster integration of clinical data into conversational assistants, cohort discovery, dashboards, and analytics pipelines.

Designed for interoperability, the MCP Server sits in front of one or more FHIR endpoints (R4 recommended) and translates high-level queries into FHIR searches, bundles responses, and attaches context metadata that helps downstream tools interpret and act on clinical results. It is useful for developers who need to augment NLP/LLM systems with verifiable clinical context or provide clinicians and analysts with natural-language search over FHIR data.

Features

• Natural-language search translation into FHIR queries
• Programmatic search API for structured filter-based queries
• Context packaging for AI tools (MCP-compliant payloads)
• Connectors for one or more FHIR servers (proxy and aggregation)
• Support for privacy-preserving filters and parameterized queries
• Health and metrics endpoints for monitoring and analytics
• Lightweight deployment options (standalone or containerized)
• Authentication and TLS configuration hooks for secure deployments

Installation / Configuration

Prerequisites:

• A running FHIR server (R4) reachable by the MCP server
• Docker (recommended) or a suitable runtime for building and running the server

Clone the repository:

git clone https://github.com/wso2/fhir-mcp-server.git
cd fhir-mcp-server

Run with Docker Compose (example):

docker-compose up -d

Or build and run locally (example with a Java/Node runtime — follow repository README for exact commands):

# Example: build
./gradlew build

# Example: run with environment variables
export FHIR_BASE_URL="https://my-fhir-server.example.org"
export MCP_PORT=8080
./gradlew run

Example environment variables / configuration (YAML or env file):

# .env or environment
FHIR_BASE_URL=https://fhir.example.org
FHIR_TOKEN=eyJhbGci...
MCP_PORT=8080
MCP_BIND_HOST=0.0.0.0
LOG_LEVEL=INFO
ENABLE_NL=true
TRUSTED_CLIENTS=client-a,client-b

TLS and authentication: configure your reverse proxy (nginx/ingress) or set up the server’s TLS config according to your deployment security requirements. The server supports bearer tokens to call upstream FHIR servers and can validate incoming requests with JWT or API keys when configured.

API Surface (common endpoints)

Example programmatic search (cURL):

curl -X POST "http://localhost:8080/mcp/search" \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceType": "Patient",
    "filters": {
      "birthDate": {"lt": "1990-01-01"},
      "active": true
    },
    "limit": 50
  }'

Example natural-language query (cURL):

curl -X POST "http://localhost:8080/mcp/nl-query" \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "List diabetic patients with last HbA1c > 8% in the past year"}'

Available Resources

• Source code and issues: https://github.com/wso2/fhir-mcp-server
• API documentation: check the repository’s docs/ or OpenAPI spec (if provided)
• Examples and sample config: repository examples/ directory
• Monitoring: /metrics endpoint for Prometheus-compatible scraping

Use Cases

• Natural-language clinical searches: allow care teams to ask plain English questions (e.g., “Which patients have had an HbA1c > 8% in the last 12 months?”) and receive a FHIR-backed list with provenance and context for auditability.
• LLM augmentation with clinical context: generate MCP payloads that include patient bundles, encounter summaries, and relevant observations so an LLM can provide summaries, clinical decision support suggestions, or question-answering with source citations.
• Cohort discovery and analytics: programmatically filter patients and extract structured datasets for downstream analytics tools or dashboards, using the programmatic search endpoint to automate exports.
• Integration in pipelines: act as a middleware layer between EHR FHIR servers and AI/analytics platforms to enforce consistent search logic, authentication, and observability.
• Research and trial recruitment: power eligibility screening by converting inclusion/exclusion criteria into MCP search requests and returning candidate lists for review.

Security and Compliance Notes

• The server handles protected health information (PHI); ensure deployments enforce TLS, proper authentication, audit logging, and least-privilege access to upstream FHIR servers.
• Validate compatibility with your FHIR server version (R4 recommended) and test generated queries against non-production data before use in clinical environments.

For detailed configuration options, advanced deployments, and example integrations with LLMs or analytics tools, see the repository’s documentation and examples directory.