The openEHR MCP Server

The MCP server that connects AI assistants and agents to openEHR REST APIs.

The Model Context Protocol (MCP) is an open standard that enables AI agents to connect to external data sources and tools in a secure and standardized way. MCP servers act as bridges between AI clients (like Claude Desktop, Cursor, or LibreChat) and domain-specific APIs and data stores.

The openEHR MCP Server exposes tools for openEHR Templates, EHR, Compositions, stored queries, and AQL execution, following the openEHR REST specification. It is designed to work alongside the openEHR Assistant MCP Server: use the Assistant for modelling, archetypes, and CKM; use this server for EHR and composition operations against an openEHR REST endpoint.

• Optional guided Prompts help orchestrate multi-step workflows (vital signs, assessments, medication review, AQL, template and composition management).

NOTE: For production-grade EHR integrations, ensure your AI model and deployment meet your organization's data privacy and compliance requirements.

WARNING: OAuth2 authorization flows are not supported yet. This server is for now intended for development and testing purposes only.

Table of Contents

• Features
• Available MCP Elements
• Transports
• Quick Start
• Common client configurations
• Development tips
• Documentation
• Contributing
• Acknowledgments

Features

• Works with MCP clients such as Claude Desktop, Cursor, LibreChat, etc.
• Exposes tools for openEHR Template definition, stored queries, AQL execution, EHR and Composition management.
• Guided Prompts for vital signs capture, patient assessment, medication review, AQL query running, and template/EHR/composition management.
• Run locally via Docker (transports: streamable HTTP and stdio)

Implementation aspects

• Made with PHP 8.4; PSR-compliant codebase
• Attribute-based MCP tool discovery (via modelcontextprotocol/php-sdk)
• Docker images for production and development (PHP-FPM + Caddy ingress in .docker/)
• Transports: streamable HTTP (Caddy on ports 80, 443, and 8342 for dev) and stdio
• Structured logging with Monolog
• Simple, environment-driven configuration

Available MCP Elements

Tools

Template Definition

• template_list - List templates (path segment e.g. adl1.4 or adl2). Optional keyword search and maxResults; when keyword is set, results are scored and sorted by relevance.
• template_get - Get a template by ID (format: e.g. opt, json, xml)
• template_upload - Upload a template (format: e.g. opt, json, xml)
• template_example_get - Get an example composition for a template (format: flat, json, xml, canonical, structured)

Stored Query Definition

• stored_query_upload - Upload a stored AQL query (optional version)
• stored_query_list - List stored queries (name filter supports namespace::name). Optional keyword search and maxResults; when keyword is set, results are scored and sorted by relevance.
• stored_query_get - Get a stored query definition by name and version

Query Execution

• query_adhoc - Execute AQL (supports offset/fetch)
• stored_query_execute - Execute stored AQL by name/version with parameters

EHR Management

• ehr_create - Create an EHR (optional subject id/namespace)
• ehr_get - Get EHR by ehr_id or by subject id/namespace (use this instead of the removed ehr_get_by_subject)
• ehr_status_get - Get EHR_STATUS for an EHR
• ehr_contribution_create - Create a Contribution for an EHR
• ehr_contribution_get - Get a Contribu

... View full README on GitHub