fhir r4 crud operations via mcp tools
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.
Unique: Implements resource-specific MCP tool routers (patient_router, observation_router, condition_router, document_reference_router) that abstract FHIR API complexity behind natural language-accessible tools, with centralized OAuth2 token management in the FHIR Client service rather than per-tool authentication
vs alternatives: Simpler than building direct FHIR REST clients because MCP tools handle OAuth2 refresh and protocol negotiation automatically; more flexible than pre-built healthcare APIs because it works with any FHIR R4-compliant server
semantic document ingestion and rag-powered retrieval
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.
Unique: Integrates semantic chunking with Pinecone vector storage and MCP tool exposure, allowing AI agents to perform RAG queries directly through MCP tools rather than requiring separate RAG API calls; combines document_reference_router with RAG services for unified document management
vs alternatives: More flexible than keyword-based document search because semantic similarity captures clinical meaning; more integrated than standalone RAG systems because documents are indexed alongside FHIR data in a single MCP interface
error handling and graceful degradation
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.
Unique: Implements error handling at multiple layers (MCP tools, services, external clients) with specific retry strategies for transient failures and graceful degradation for permanent failures, preventing cascading failures across the system
vs alternatives: More resilient than simple error propagation because transient failures are retried automatically; more observable than silent failures because errors are logged with context for debugging
healthcare terminology lookup and medical code validation
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.
Unique: Exposes LOINC terminology lookup as an MCP tool, allowing AI agents to resolve medical codes during natural language interactions without separate API calls; includes in-memory caching to reduce LOINC API load for repeated queries
vs alternatives: Simpler than building custom code mapping systems because LOINC is the standard; more integrated than standalone terminology services because it's accessible through the same MCP interface as FHIR operations
oauth2 authentication and token lifecycle management
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.
Unique: Centralizes OAuth2 token management in the FHIR Client service with automatic refresh logic, preventing individual MCP tools from handling credentials directly; uses environment-based configuration for secure credential injection rather than hardcoding
vs alternatives: More secure than per-tool authentication because credentials are managed centrally; more reliable than manual token refresh because automatic expiration detection prevents failed API calls
mcp tool orchestration and fastmcp framework integration
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.
Unique: Uses FastMCP framework to automatically handle MCP protocol compliance and tool registration, with specialized routers for different FHIR resource types mounted onto a single FastMCP instance; eliminates manual protocol handling and schema validation
vs alternatives: Simpler than building custom MCP servers because FastMCP handles protocol negotiation; more maintainable than REST APIs because tool schemas are co-located with implementation
multi-resource fhir search and filtering
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.
Unique: Generic router provides fallback search capability for any FHIR resource type, translating natural language search intents into FHIR search parameter queries without requiring resource-specific tool implementations
vs alternatives: More flexible than hardcoded search endpoints because it works with any FHIR resource; more user-friendly than raw FHIR search syntax because natural language queries are translated automatically
configuration management with encrypted credential storage
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.
Unique: Provides encryption utilities for sensitive configuration values alongside environment-based configuration, enabling secure credential storage without external secret management systems
vs alternatives: Simpler than external secret managers for small deployments; more flexible than hardcoded configuration because environment-based approach supports multiple deployment targets
+3 more capabilities