fhir resource search with natural language translation
Translates natural language queries into FHIR search operations by mapping user intent to FHIR search parameters, leveraging the fhirpy client library (v2.0.15+) to execute parameterized searches against FHIR R4 servers. The server implements a tool-based interface where queries like 'Get allergy history for patient 53373' are decomposed into structured FHIR search calls with resource type, search parameters, and filters, returning paginated results with full FHIR resource bundles.
Unique: Implements dual-layer abstraction: MCP tool interface wraps fhirpy client library, enabling LLM agents to invoke FHIR searches without direct API knowledge while maintaining full FHIR R4 compliance through standardized parameter mapping
vs alternatives: Provides natural language FHIR search through MCP protocol (enabling any MCP-compatible AI tool integration) rather than requiring direct REST API calls or custom healthcare data adapters
fhir resource crud operations with oauth-secured access
Exposes create, read, update, and delete operations for FHIR resources through MCP tools (create_fhir, read_fhir, update_fhir, delete_fhir) with automatic OAuth 2.0 client credential flow for FHIR server authentication. Each operation validates input against FHIR R4 schemas using Pydantic models, constructs appropriate HTTP requests via fhirpy, and returns typed FHIR resources or error responses with full audit trail support through OAuth token tracking.
Unique: Implements dual-role OAuth architecture where the MCP server acts as OAuth client to FHIR servers, handling token lifecycle (acquisition, refresh, expiration) transparently while exposing simple MCP tool interfaces — developers never touch OAuth directly
vs alternatives: Abstracts OAuth 2.0 PKCE complexity away from AI agents compared to direct REST API integration, reducing security misconfiguration risk while maintaining full FHIR R4 compliance
fhir capability statement retrieval and server metadata discovery
Fetches and parses the FHIR server's CapabilityStatement resource (via GET /metadata endpoint) to expose supported resource types, search parameters, operations, and conformance details. The server caches the capability statement and exposes it through the get_fhir_capabilities MCP tool, enabling AI agents to dynamically discover what FHIR operations are available before attempting queries, with automatic fallback to R4 defaults if the server doesn't expose full metadata.
Unique: Caches FHIR CapabilityStatement at server initialization and exposes it as an MCP tool, allowing AI agents to introspect server capabilities without direct HTTP calls — bridges the gap between dynamic FHIR servers and static LLM knowledge
vs alternatives: Provides server-agnostic capability discovery through MCP protocol rather than requiring agents to make raw HTTP calls to /metadata, enabling safer and more informed query generation
dual-role oauth 2.0 authentication with pkce flow
Implements a bidirectional OAuth 2.0 system where the MCP server acts as both an OAuth server (authenticating MCP clients via PKCE) and an OAuth client (accessing external FHIR servers). The server manages token lifecycle including acquisition, refresh, and expiration using Pydantic-validated configuration, with support for multiple FHIR server endpoints and per-client credential isolation. PKCE (Proof Key for Code Exchange) is enforced for all flows to prevent authorization code interception attacks.
Unique: Implements dual OAuth roles (server + client) within a single MCP server, enabling transparent credential management for AI agents while maintaining OAuth security standards — agents never see FHIR server credentials, only MCP-level tokens
vs alternatives: Provides centralized OAuth token management for multiple FHIR servers compared to distributing credentials to each AI agent, reducing credential exposure surface and enabling audit trails
mcp protocol bridging with flexible transport (http and stdio)
Exposes FHIR capabilities through the Model Context Protocol (MCP) using both HTTP and STDIO transport mechanisms, enabling integration with diverse AI tool architectures. The server implements the MCP tool interface specification, where each FHIR operation (search, read, create, etc.) is registered as an MCP tool with typed input schemas and output specifications. Transport selection is configurable at startup, allowing deployment as either a long-running HTTP server (for cloud/container environments) or a STDIO process (for local AI tool integration).
Unique: Implements MCP protocol as a first-class abstraction layer, supporting both HTTP and STDIO transports from a single codebase — enables seamless integration with any MCP-compatible AI tool without custom adapters
vs alternatives: Provides standardized MCP protocol integration compared to custom REST API wrappers, enabling AI tools to discover and call FHIR operations dynamically with type-safe schemas
pydantic-based configuration validation and environment management
Uses Pydantic v2 models to validate and type-check all configuration parameters (OAuth credentials, FHIR server URLs, transport settings) at server startup, with support for environment variable injection and .env file loading. Configuration is immutable after validation, preventing runtime configuration drift. The system enforces required fields, type coercion, and custom validators (e.g., URL format validation, credential format checks) before the server initializes, failing fast with detailed error messages if configuration is invalid.
Unique: Enforces configuration validation at server startup using Pydantic models, preventing invalid credentials or URLs from causing runtime failures — configuration errors are caught immediately rather than during first FHIR operation
vs alternatives: Provides type-safe configuration validation compared to manual string parsing, reducing configuration errors and enabling IDE autocomplete for configuration objects
asynchronous fhir operations with aiohttp-based http client
Implements all FHIR operations (search, read, create, update, delete) using Python's asyncio framework with aiohttp>=3.12.13 for non-blocking HTTP requests. The server processes multiple concurrent FHIR queries without blocking, enabling high-throughput scenarios where multiple AI agents query the same FHIR server simultaneously. Connection pooling and keep-alive are configured automatically, reducing latency for repeated requests to the same FHIR server.
Unique: Leverages Python asyncio for non-blocking FHIR operations, enabling the server to handle multiple concurrent AI agent requests without thread overhead — single-threaded async model scales better than thread pools for I/O-bound healthcare data access
vs alternatives: Provides non-blocking FHIR access compared to synchronous REST clients, enabling higher throughput and lower latency for multi-agent healthcare AI systems
fhir r4 resource type abstraction via fhirpy client library
Abstracts FHIR R4 resource manipulation through the fhirpy>=2.0.15 client library, which provides object-oriented interfaces for all FHIR resource types (Patient, Observation, Medication, etc.). The server leverages fhirpy's built-in FHIR validation, resource serialization, and search parameter mapping, eliminating the need for manual JSON construction or FHIR spec knowledge. Resource operations are type-safe through fhirpy's resource classes, reducing serialization errors and enabling IDE autocomplete.
Unique: Delegates FHIR resource handling to fhirpy library, providing object-oriented abstractions for all FHIR R4 resource types — developers work with Python objects instead of raw JSON, reducing FHIR spec knowledge requirements
vs alternatives: Provides type-safe FHIR resource manipulation compared to raw REST API calls, reducing serialization errors and enabling IDE autocomplete for FHIR resources
+1 more capabilities