I’d like to share something I’ve been working on for a while: an openEHR Assistant MCP Server.
As you all know, I am a very firm believer in what openEHR has to offer as a standard. However, I am very much aware of the fact that developing and modelling according to the openEHR Specifications is not easy… Which may discourage developers and modellers new to the openEHR Community.
What does it do?
The openEHR Assistant MCP Server exposes openEHR knowledge artefacts and modelling workflows to LLM-based assistants, using the Model Context Protocol. By combining deterministic tools, canonical resources, and guided prompts, it supports exploration, comparison, explanation, and early-stage archetype or template design, while remaining aligned with openEHR semantics and governance.
I hope that this assistant may help those in need of a hand to get started. I have made the project available on GitHub. Do check it out and let me know what you think - thanks!
Thank you so much for publishing and hosting this very useful tool, Sebastian!
I’m wondering, and forgive me if it’s actually already doing this, but could it be possible to incorporate the kind of information contained in the child pages of https://openehr.atlassian.net/wiki/x/AQAqEg? That could be very useful if using an LLM to model archetypes. If possible, which format would be the best for ingesting the information?
Thanks, good suggestion. It contains now a very small and compacted version of those pages but also others, in a form of “guides”, in markdown format. Guides are exposed as resources an referred in system prompts - that’s the way it gets used.
I am often tweaking them and trying to measure impact or looking of improvements - but it is a slow going process, so it will take a bit more time a some versions. I already have prepare some new materials for upcoming versions, and I will reconsider also those you indicated. Also hoping some others will also help on this (hence open source state), as you know …it is not always easy to review the modeling process internals when you are not doing modeling …
Thanks, that’s good to hear! My thinking about those resources is that they are living documents and will continue receiving updates into the future. Is there a way to connect the MCP server directly to the documents (or a different version of them) so that you or someone else don’t need to update things manually all the time?
you can fork the repo, make you change and once you’ll push on your github, out might have another docker image, which (if you have docker) you could run it locally - there is some doc about --transport=stdio in the readme.md file.
if you have docker locally, you can also just clone the repo locally, make your chnages, then build the image, then host it somewhere or run it with the same --transport=stdio - this is the way I tested and developed in the last week developing.
Most of these MCP clients (Claude, cursor, Librechat) allows running it locally, sometime labelled as dev-mode.
Hi, it’s nice to see the AI movement reached openEHR
We are doing some tests with embeddings, but it’s for a different use case: to understand the models created (templates, archetypes) to derive other elements, like queries.
Mostly by summarizing (using ChatGPT and Claude) the ADL/AOM Specifications, and then combining it with similar summarization (by Rovo) of the relevant Wiki pages we have.
The initial structure (so the way I choose to organize it in files, folders etc) is mostly from me, aligned also how the application code is designed, trying to reuse some concepts and make them maintainable.
Of course, not all of these went well right form the beginning, I had to try several prompts and tasks until I got something workable, and then I still need to read carefully and edit myself the texts, as sometimes is “not focused” let’s put it that way. But nevertheless, the guides are still subject to my lack of knowledge/experience with the modeling process, so I would invite anyone more “connected” to review them and help improve them.
I’ve made some improvements, released a new version (0.11.0).
It is now adhering much better to the guides in the repo : whatever the required workflow is, it will stick to relevant rules and workflow much better; you may also see some new tool calls to fetch the guides at certain moments. The output of tasks looks to me also generally better, but there might be some bias or perhaps the model itself inproved. I also manage to get it working with Chatgpt (yet it is still not used as easy as with Claude).
In case you already have a previous version installed, I would suggest reinstalling or reconnecting, as some changes are related to the initialization and registration phase, besides the new tools provided.
New tools:guide_adl_idiom_lookup (quick ADL constraint pattern lookup without
prompting from scratch), plus expanded type_specification_search/get coverage.
The server now exposes 10 MCP tools in total.
Expanded prompts: 15 guided MCP prompts now cover the full modeling lifecycle,
from archetype and template design/review, through composition building, AQL query
authoring, terminology resolution, and language translation/syntax fixing.
27 implementation guides (Markdown resources served via openehr://guides/...)
covering archetypes, templates, AQL, simplified formats (FLAT/STRUCTURED/CANONICAL),
and RM structural concepts, a substantial expansion over the initial guide set.
Improved guide adherence and workflow fidelity: the server now reliably fetches
relevant guides at the right workflow steps, rather than relying solely on initialization.
Compatibility extended: the hosted server works reliably with Claude, Cursor, and
LibreChat; ChatGPT compatibility was also explored.
Introducing two companion projects
Alongside the MCP server, two new repositories have been published that significantly
extend usability:
An AI plugin suite for Claude Code and Cursor that adds the workflow layer
on top of the MCP server. It provides:
Skills that instruct the AI when and how to load guides and invoke MCP tools
(e.g. archetype-authoring, archetype-lint with 22 normative rules, template-authoring using the CGEM framework, composition-builder, aql-query, demographic-modeling, platform-design).
Slash commands for common tasks: /archetype-search, /archetype-lint, /archetype-review, /template-explain, /aql-designer, /format-data, /ehr-structure, /terminology, /type-spec, /adl-idiom, and more.
A clinical-modeler agent for working directly with local archetype/template files
in your workspace.
Offline reference material (ADL/AQL syntax cheatsheets, RM type reference) for when
the MCP server is not available.
A registry/marketplace of reusable AI plugins (Claude Code skills, Cursor rules, MCP
configs), of which openehr-assistant-plugin is the first published entry. It provides
a discoverable, versioned catalog so the community can share and find AI workflow
plugins, with the openEHR plugin serving as the reference implementation.
As always, feedback, issues, and PRs are very welcome. The guides in particular are an
area where input from experienced modelers would be most valuable, if something doesn’t
reflect actual CKM modeling practice, please open an issue or PR on the repo.
v0.16.0 of the MCP server shipped today, paired with plugin v0.6.0 for Cursor & Claude Code.
What changed
Two new guide categories.specs/ holds 30 specification digests across AM, AM2, BASE, RM, QUERY, TERM, LANG, CDS, SM, ITS-REST — each 250–900 words, tracking the openEHR development branch. howto/ holds toolchain recipes; the first, spec-lookup, documents the llms.txt site index and the .md twin URL pattern (every *.html spec page has a Markdown counterpart at the same path). Legacy rm/ retired in favour of specs/rm-*.
Curated worked examples at openehr://examples/{kind}/{name} — 12 AQL queries, 4 FLAT payloads, 1 STRUCTURED, and 7 CKM-published .adl archetypes — surfaced by two new tools examples_search / examples_get.
Three conditional routing policies (Spec-Lookup-First, Digest-First, Examples-First) added to the server instructions.
BMM refresh with a new LANG component;
Plugin v0.6.0 absorbs all of the above and adds 5 commands (/archetype-rationale, /template-from-form, /archetype-impact, /archetype-diff, /template-diff), 2 subagents (ckm-scout, spec-researcher), and a lint-on-save hook.
Why this matters
Grounded spec lookup, cheap. Before v0.16, answering “what does the spec say about X?” either burned tens of thousands of tokens on an HTML fetch or relied on vague recall of which release PDF had the paragraph. The digest → .md twin → BMM cascade (documented in howto/spec-lookup) gives short, citeable answers at a fraction of the context cost. The spec-researcher subagent encapsulates it so spec research doesn’t eat your main session.
Reference patterns over invention. Asking for an AQL query, a FLAT payload, or a new archetype now adapts a published pattern rather than improvising on a Friday afternoon. The 7 gold-standard archetype examples (blood pressure, problem/diagnosis, medication order, encounter, procedure, anatomical location, translation requirements) serve as prior art for each RM entry type.
How to use it
Install the plugin — Claude Code: claude plugin add cadasto/openehr-assistant-plugin; Cursor: from the Git URL.
Point it at an MCP endpoint (hosted, or self-run).
Open a repo containing your .adl / .oet / .aql files and try:
/archetype-impact <archetype-id> — who in my workspace uses this archetype?
dispatch ckm-scout "<concept>" — reuse-first CKM search before authoring from scratch
Feedback especially welcome on whether specs/ digest length (≤900 words per document) feels right for day-to-day use, gaps in the curated examples, or anything else you may find it.
A small clarification that may be useful - this has come up a couple of times recently. Some people assume that this MCP connects directly to an openEHR CDR (e.g., from Cadasto), but that is not the case.
In practice, it interacts with the openEHR International CKM instance and a broad set of published specifications. A more accurate way to think about it is as a domain-aware assistant focused on openEHR specifications and modeling, available to support you when working within an agentic environment.
…