Install

Two things to install, and you only need the first. The MCP server works with any MCP client on its own; the plugin adds guided workflows on top of it in Claude Code and Cursor.

Just want to try it?

Point your client at the hosted endpoint — https://openehr-assistant-mcp.apps.cadasto.com/ — and skip straight to Use cases. Nothing to run locally.

Everything below is pulled from each product's own install guide when this site is built, so it cannot fall out of step with the software it describes.

MCP server

How to connect an MCP client to the openEHR Assistant MCP Server — either the hosted endpoint (no install) or a local instance. For contributing to the server itself, see development.md.

Tip: For the best experience, also install the user-facing openEHR Assistant Plugin (skills, prompts, and agents that guide AI assistants through openEHR workflows).

Option 1 — Hosted endpoint (no install)

The fastest path: point your client at the hosted server.


URL	`https://openehr-assistant-mcp.apps.cadasto.com/`
Transport	`streamable-http`

{
  "mcpServers": {
    "openehr-assistant-remote": {
      "type": "streamable-http",
      "url": "https://openehr-assistant-mcp.apps.cadasto.com/"
    }
  }
}

Option 2 — Run locally with Docker

Use this to run your own instance (also the basis for contributing).

Prerequisites: Docker + Docker Compose, Git.

git clone https://github.com/cadasto/openehr-assistant-mcp.git
cd openehr-assistant-mcp
cp .env.example .env          # defaults work for most users
make up-dev                   # start dev containers
make install                  # install Composer dependencies (in the container)

Local endpoints once the stack is up:

Endpoint	URL
Dev HTTP (host)	`http://localhost:8343/`
Dev HTTP (from another container, e.g. LibreChat)	`http://host.docker.internal:8343/`
Named host (optional)	`http://openehr-assistant-mcp.local:8343/`

To use openehr-assistant-mcp.local, add 127.0.0.1 openehr-assistant-mcp.local to your hosts file. If it doesn't resolve, just use http://localhost:8343/. (make and Docker commands are documented in development.md.)

Option 3 — Run locally via stdio

For clients that launch the server process directly.

# From the dev container:
docker compose --env-file .env -f .docker/docker-compose.yml -f .docker/docker-compose.dev.yml \
  exec app php public/index.php --transport=stdio

# Or from the published image:
docker run --rm -i ghcr.io/cadasto/openehr-assistant-mcp:latest php public/index.php --transport=stdio

Client configurations

Add one server entry to your client. Pick the transport that matches your setup (hosted / local HTTP / stdio).

{
  "mcpServers": {
    "openehr-assistant-mcp": {
      "type": "streamable-http",
      "url": "https://openehr-assistant-mcp.apps.cadasto.com/"
    },
    "openehr-assistant-mcp-http": {
      "type": "streamable-http",
      "url": "http://host.docker.internal:8343/"
    },
    "openehr-assistant-mcp-stdio": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "ghcr.io/cadasto/openehr-assistant-mcp:latest",
        "php", "public/index.php", "--transport=stdio"
      ]
    }
  }
}

Claude Desktop

Add the hosted URL via Menu → Settings → Connectors → Add custom connector, or use Menu → Developer → Edit Config and add one of the entries above.

LibreChat (streamable HTTP)

mcpServers:
  openehr-assistant-mcp:
    type: streamable-http
    url: http://host.docker.internal:8343/

Cursor

Cursor Settings → MCP → Add server, then choose: - Hosted: type=streamable-http, url=https://openehr-assistant-mcp.apps.cadasto.com/ - Local dev: type=streamable-http, url=http://host.docker.internal:8343/ - Local stdio: the Docker command above.

IntelliJ Junie

Settings → Tools → Junie → MCP Servers (wording varies by version). Add a Streamable HTTP URL (hosted or http://host.docker.internal:8343/) or the stdio Docker command, then refresh/restart Junie so tools are discovered.

Plugin

This plugin is distributed for both Claude Code (.claude-plugin/) and Cursor (.cursor-plugin/). Skill, command, agent, and rule content is shared; only the manifest and hook layer differ.

This is the user-facing plugin — for clinical modelling, AQL, CKM discovery, and specification lookup. If you instead want to build the openEHR Assistant tooling (MCP tools, guides, examples), see the maintainer openehr-assistant-dev plugin.

Claude Code

Install (from the Cadasto marketplace)

/plugin marketplace add cadasto/plugin-marketplace
/plugin install openehr-assistant@cadasto

The marketplace name is cadasto, so installed plugins are addressed as <plugin>@cadasto.

Install (local working copy, for development)

claude plugin add /path/to/openehr-assistant-plugin

Update / inspect

/plugin marketplace update cadasto
/plugin update openehr-assistant

claude plugin details openehr-assistant   # component inventory + projected token cost

A session restart is required for an update to take effect.

Cursor

Add this repository as a plugin (Cursor Settings → Plugins, via Git URL or local path). The repo root contains .cursor-plugin/plugin.json; skills, commands, agents, rules, the bundled MCP config (.mcp.json), and the Cursor hook config (hooks/cursor-hooks.json) are declared there. After changing content locally, reload or reinstall the plugin so Cursor picks it up.

MCP wiring

Unlike the maintainer plugin, this plugin bundles a .mcp.json so it works out of the box: it points at the hosted openEHR Assistant MCP server (streamable-http). Skill / command allowed-tools and agent tools: entries reference mcp__openehr-assistant__* tools resolved from that server.

To use a local or stdio MCP server instead, override the bundled config in your host. For server installation, transports, and client-specific configuration, see the openehr-assistant-mcp — Quick Start and AGENTS.md.

Subagents & MCP permissions

The plugin's agents (ckm-scout, spec-researcher, and clinical-modeler's read-only lookups) call MCP tools. Agent frontmatter (tools:) grants the capability, but your host's permission policy must still allow the server — otherwise a subagent can be silently denied CKM/guide access even though the same tools work in the main session.

If you hit that, pre-approve the server in your project's .claude/settings.json (the plugin repo already ships this in its own .claude/settings.json):

{
  "permissions": {
    "allow": [
      "mcp__openehr-assistant",
      "mcp__plugin_openehr-assistant_openehr-assistant"
    ]
  }
}

Both namespaces are listed because the server may be wired as the plugin-bundled one (mcp__plugin_openehr-assistant_openehr-assistant__*) or registered directly under its plain name in a project/user .mcp.json (mcp__openehr-assistant__*). All openEHR Assistant tools are read-only, so allowing the whole server is safe. The agents fail loud with BLOCKED: … and route the lookup back to the main session when this isn't in place.

Mount shape matters for the agents

The same server yields a different tool-id namespace per mount, and agent tools: entries are matched literally:

How the server is mounted	Live tool ids
Project or user `.mcp.json` under the key `openehr-assistant`	`mcp__openehr-assistant__<tool>`
This plugin's bundled `.mcp.json`	`mcp__plugin_openehr-assistant_openehr-assistant__<tool>`
claude.ai connector	`mcp__claude_ai_<connector>__<tool>`

The three agents ship both of the first two forms, so they work under either without configuration. The connector shape is named after your connector, so the plugin cannot predict it: under a connector-only mount the agents lose MCP access (and ckm-scout, whose tools: is MCP-only, is refused with would be spawned with zero tools). If that is your setup, register the server in a project .mcp.json as well — that is the one mount the agents can rely on:

{
  "mcpServers": {
    "openehr-assistant": {
      "type": "streamable-http",
      "url": "https://openehr-assistant-mcp.apps.cadasto.com/"
    }
  }
}

The main session is unaffected either way — only agent tools: matching is namespace-sensitive.

Which server does the plugin talk to?

The plugin bundles a .mcp.json registering the hosted server under the name openehr-assistant. If you also configure the server by hand, use that same name — otherwise you end up with two client entries pointing at one endpoint.

Once both are in place, Features lists everything you can now reach, and Use cases shows it in action.