RFC: What should a great FHIR MCP server look like?

[angela-helios]

This is an open design discussion — an RFC, not a decision. We want to build an HL7 FHIR MCP server that we'd be proud to put in front of the FHIR community, and we'd rather argue about the shape before writing it. Tell us where we're wrong.

The question we're really asking: when an AI agent needs to work with FHIR data, what should the tool between them look like?

---

What MCP is (one paragraph)

The Model Context Protocol is an open JSON-RPC 2.0 protocol that standardizes how applications expose context and actions to LLMs. A server offers three primitives: tools (model-invokable functions with JSON-Schema inputs), resources (readable, URI-addressed context), and prompts (reusable templated workflows). Standard transports are stdio (local subprocess — how desktop/IDE agents launch a server) and streamable HTTP (remote/multi-user, with SSE for server→client streaming).

The goal

Make a FHIR server directly usable by LLM agents without those agents hand-rolling FHIR REST calls, FHIRPath, or SQL-on-FHIR. The MCP server should be a thin, safe bridge from MCP's primitives to real FHIR capabilities — not a reimplementation of FHIR, and not a chatbot.

---

Our opinion: what a great FHIR MCP server needs

The category is young, and most of what exists today is a thin CRUD wrapper. That's table stakes, not the bar. Here's where we think the bar actually is:

1. A small, well-named tool set — but wider than CRUD. search / read / create / update / delete are the price of entry. The value is in the analytical surface most stop short of: evaluate a FHIRPath expression, run a SQL-on-FHIR ViewDefinition, resolve terminology ($lookup / $validate-code / $expand). An agent that can analyze FHIR, not just fetch it, is the difference.

2. Token efficiency is a correctness concern, not a nicety. FHIR resources are large; a naive search that inlines a full Bundle blows the context window and degrades the agent. Summaries (_summary / _elements), sane paging defaults, and returning resource URIs the agent can fetch on demand instead of always inlining are first-class design requirements.

3. Safety is what separates a product from a demo. Reads default-on, writes default-off behind explicit config and an authorized scope. Every tool call is audited with the resolved principal + tenant. Destructive operations require explicit confirmation. Tool availability should reflect the caller's scopes — a read-only token never even sees the write tools.

4. Errors should teach the model. When a write is malformed, hand back the FHIR OperationOutcome detail so the agent can self-correct on the next turn, rather than a bare failure.

5. Multi-tenancy and FHIR-version selection must be first-class, resolved once per session and threaded to every tool — the same isolation guarantees the REST API gives.

We'd love the community's take on this bar — especially where it's too low or too high.

---

Proposed technical decisions (arguable)

Build on the official Rust MCP SDK (rmcp), don't hand-roll the protocol. It's mature, edition-2024, permissively licensed, and ships a typed #[tool] macro plus both transports and OAuth. Hand-rolling JSON-RPC + session/capability handshakes is undifferentiated work.

Ship stdio first, then streamable HTTP. stdio is how local agents launch a server (single-user, the process boundary is the trust boundary). Streamable HTTP is the modern remote/multi-user transport; the deprecated HTTP+SSE transport isn't worth building.

Share one service layer with the REST API — don't fork FHIR logic. If MCP tools and REST handlers each orchestrate the storage traits independently, they will drift (search-param parsing, _include, OperationOutcome shaping, tenant checks). Extract a version-agnostic FHIR service both call. Pragmatically this can be phased so it doesn't block an MVP.

Auth maps to real principals + scopes. Local stdio is single-user (principal/tenant from config). Remote HTTP validates a bearer token to a principal with SMART scopes; write-gating and tool availability derive from those scopes.

Result shaping is built in (summary projections, paging, byte/token budgets, URIs-over-inlining) — see principle #2.

Sketch of the surface

• Tools: fhir_search, fhir_read, fhir_history, fhir_capabilities, fhirpath_evaluate, sof_run_view (SQL-on-FHIR), terminology_lookup / validate_code / expand_valueset, and (gated) fhir_create / update / patch / delete.
• Resources: fhir://metadata (CapabilityStatement), fhir://{type}/{id} (fetch-on-demand target), fhir://search-parameters/{type} (so the model forms valid queries).
• Prompts: summarize-patient, build-cohort.

A phased path

1. This discussion → ratify the principles and the SDK/transport/shared-service decisions.
2. Read-only MVP over stdio: search / read / capabilities / fhirpath_evaluate.
3. Streamable HTTP + auth + audit.
4. Analytics + terminology tools, resources, and prompts.
5. Gated writes, fully audited.

Each phase is independently shippable.

---

Open questions for the community

1. Is the analytical surface (FHIRPath, SQL-on-FHIR) the right differentiator, or should an MCP server stay CRUD-only and leave analytics to the client?
2. How aggressive should default result shaping be — summaries always, with the full resource one fetch away? Where's the line between "safe for the context window" and "hiding data the agent needs"?
3. For writes, is scope + explicit config + per-call confirmation enough, or should there be a human-in-the-loop step the protocol surfaces?
4. Should the server embed its own store (zero extra services for local use) or always connect to a running FHIR server?
5. What does good error feedback look like for an agent — how much of the OperationOutcome do we hand back?
6. Any PHI / de-identification expectations we should bake in vs. leave to scopes + tenancy + audit?

References

• Model Context Protocol — https://modelcontextprotocol.io
• MCP specification — https://spec.modelcontextprotocol.io
• Official Rust SDK (rmcp) — https://github.com/modelcontextprotocol/rust-sdk

---

Please comment with disagreements, missing requirements, or "you're overthinking this." We'll fold the discussion into a ratified design before any code lands.