FHIR MCP

Exposes full Create, Read, Update, Delete operations on FHIR R4 resources (Patient, Observation, Condition, Medication, DocumentReference) through dedicated MCP tool routers that abstract OAuth2 authentication and FHIR API communication. Each resource type has a specialized router that handles resource-specific validation, transformation, and server communication via a centralized FHIR Client service that manages token refresh and HTTP protocol compliance.

Ingests clinical documents (PDFs, text) into a vector database (Pinecone) using semantic chunking and embeddings, enabling AI agents to perform semantic search across document collections without full-text indexing. The system chunks documents into semantic units, generates embeddings via an embedding service, stores vectors with metadata in Pinecone, and retrieves relevant chunks based on cosine similarity to natural language queries, with optional re-ranking for relevance.

Implements comprehensive error handling across MCP tools, service layers, and external API calls with specific error types (authentication failures, FHIR validation errors, vector database timeouts) and graceful degradation strategies. The system returns detailed error messages to MCP clients, logs errors with context for debugging, retries transient failures (network timeouts, rate limits), and falls back to alternative implementations when primary services are unavailable.

Provides standardized medical code lookup and validation through integration with the LOINC API, enabling AI agents to resolve clinical terminology (lab codes, observation types, medication codes) to standard healthcare vocabularies. The system queries LOINC for code definitions, descriptions, and related codes, with caching to reduce API calls and support for code-to-description and description-to-code lookups.

Manages OAuth2 authentication flows and token lifecycle (acquisition, refresh, expiration handling) for FHIR server communication through a centralized FHIR Client service. The system handles client credentials grant flow, automatic token refresh before expiration, and credential rotation, abstracting authentication complexity from individual MCP tools so they can focus on business logic.

Implements the Model Context Protocol (MCP) server using the FastMCP framework, which handles MCP protocol compliance, tool registration, and request routing. The system mounts specialized routers (patient_router, observation_router, condition_router, document_reference_router, generic_router) onto a FastMCP instance, enabling MCP-compatible clients (Claude Desktop, custom consumers) to discover and invoke tools through a standardized protocol with automatic schema validation and error handling.

Provides search and filtering capabilities across FHIR resources using FHIR search parameters (date ranges, codes, patient identifiers, status filters) through a generic_router fallback that handles any FHIR resource type. The system translates natural language search intents into FHIR search parameter queries, executes searches against the FHIR server, and returns paginated results with metadata, supporting complex filters without requiring users to know FHIR query syntax.

Manages application configuration (FHIR server URLs, API keys, Pinecone credentials) through environment-based configuration with optional encryption for sensitive values. The system loads configuration from environment variables or encrypted config files, validates required settings at startup, and provides utilities for encrypting/decrypting credentials without exposing them in logs or version control.

Provides Docker and Docker Compose configurations for containerized deployment of the FHIR MCP server, enabling reproducible environments across development, testing, and production. The system includes a Dockerfile with Python 3.13+ runtime, dependency installation via uv, and Docker Compose configuration for multi-container orchestration with FHIR server, vector database, and MCP server services.

Implements a three-layer architecture separating MCP protocol handling (FastMCP routers), business logic (FHIR/RAG services), and external service integration (FHIR Client, Pinecone, LOINC API). Each layer has distinct responsibilities: routers handle tool invocation and schema validation, services implement domain logic and error handling, and integration clients manage external API communication with retry logic and connection pooling.

Processes multiple clinical documents in batch mode, extracting text from PDFs, splitting into semantic chunks based on clinical structure (sections, paragraphs), generating embeddings for each chunk, and storing in Pinecone with metadata. The system handles document parsing errors gracefully, tracks ingestion status per document, and supports resumable batch processing for large document collections.