FHIR MCP Server Explained: Letting Claude and Cursor Query Your EHR Without Hallucinating Codes

A healthcare product engineer asks Cursor to find the latest A1C result for a test patient. An operations analyst asks Claude to identify the diagnosis codes documented in a patient’s record.

Both requests sound simple. But the AI application does not automatically know which FHIR resources the EHR supports, which patient record is correct, how the organization represents laboratory results, or which clinical terminology version applies.

Without controlled access to the EHR and an authoritative terminology service, the model may return a code that appears credible but is wrong. It could use the wrong code system, attach an incorrect display name, select an inactive concept, or return a valid code that is not permitted for the intended workflow.

A FHIR MCP Server can reduce this risk.

It gives Claude, Cursor, and other Model Context Protocol-compatible applications a governed way to search FHIR data and validate clinical codes through approved tools. Instead of relying on model memory, the architecture requires the AI application to retrieve and verify information from controlled healthcare systems. However, an MCP server cannot make a language model incapable of hallucinating. The more defensible goal is:

Prevent an unsupported AI-generated code from being accepted as authoritative or entering an EHR workflow without validation.

This guide explains how a production FHIR MCP architecture works, where it can fail, and what healthcare technology teams need before connecting AI agents to EHR data.

What Is a FHIR MCP Server?

The Model Context Protocol, or MCP, is an open protocol that allows large language model applications to connect to external tools and data sources. The current stable MCP specification defines an architecture involving hosts, clients, and servers. MCP servers can expose named tools that allow a model to query databases, call APIs, or perform controlled operations.

In a FHIR MCP architecture, Claude or Cursor can operate as the user-facing MCP environment. The FHIR MCP Server exposes approved healthcare capabilities that the AI application can discover and invoke. Those capabilities may connect to:

• An EHR’s FHIR API
• A managed FHIR repository
• A SMART on FHIR authorization service
• A FHIR terminology server
• A patient identity service
• A healthcare integration platform
• An organizational mapping repository
• An audit and provenance service

FHIR and MCP serve different purposes.

FHIR defines how healthcare information such as patients, conditions, observations, encounters, medications, and procedures is represented and exchanged.

MCP defines how an AI application discovers and invokes tools that can retrieve or process information.

SMART on FHIR provides OAuth-based authorization patterns for applications accessing FHIR systems.

Terminology services determine whether clinical codes exist and whether they are valid for a specific use.

A FHIR MCP Server coordinates access across these components. It is not itself an HL7 standard, an EHR database, or a replacement for existing healthcare authorization controls.

AWS demonstrated the practicality of this architecture in January 2026 by publishing an open-source MCP server for AWS HealthLake. AWS describes support for FHIR searches, patient-level operations, import and export jobs, and read-only operations. This demonstrates that MCP can simplify controlled access to FHIR data, but organizations still need their own identity, policy, terminology, and governance layers.

What “Without Trusting Hallucinated Codes” Means

No external tool can guarantee that an AI model will never generate an incorrect code or clinical interpretation. A model may still misunderstand a phrase, confuse similar concepts, or propose a code that is not supported by the underlying documentation. 

The architecture must therefore assume that the model can be wrong. A well-designed FHIR MCP Server reduces the consequences of that error by enforcing three rules:

1. An unverified model-generated code cannot be presented as an authoritative result.
2. The model cannot silently substitute its own code when terminology validation fails.
3. The model cannot write a proposed code into the EHR without required policy checks and human approval.

The model may help interpret the user’s intent. An authoritative terminology service determines whether a code exists and is permitted. The EHR determines whether the requesting identity is authorized to access or change the record.

A clinician, coding professional, or other authorized reviewer still determines whether the result is clinically and operationally appropriate.

How the FHIR MCP Architecture Works

A production implementation normally requires several independently controlled layers.

Architecture layer	Primary responsibility
Claude or Cursor	Interprets the request and selects an available tool
MCP client	Connects the AI application to the approved MCP server
FHIR MCP gateway	Exposes task-specific healthcare tools
Policy and context layer	Evaluates identity, tenant, role, patient context, purpose, and requested action
SMART authorization	Controls downstream access to the EHR or FHIR repository
FHIR and terminology services	Retrieves patient data and verifies coded concepts
Audit and provenance layer	Records how information was accessed, validated, and used

The interaction should follow a controlled sequence. First, an authorized user submits a request. The AI application determines whether an approved MCP tool is required.

The MCP gateway then evaluates the request. It should identify who initiated it, which patient or population is involved, what purpose the request serves, and whether the selected tool is allowed.

Only after those checks should the gateway call the EHR’s FHIR API using separately authorized downstream credentials.

When a result contains clinical codes, the gateway should validate them through an approved terminology service. The final response can then contain the verified code, official display, code system, version, validation status, source resource, and retrieval time.

The language model explains the result. It does not become the source of truth.

Why Task-Specific MCP Tools Are Safer Than Generic FHIR API Access 

A weak implementation may expose the complete FHIR REST interface through one general-purpose MCP tool. The AI agent would then be responsible for choosing the resource, search parameters, date range, requested fields, and operation.

That design offers flexibility, but it also delegates too much operational control to the model.

The agent may:

• Retrieve more patient data than the workflow requires
• Use an unsupported search parameter
• Search the wrong resource
• Confuse patient and encounter context
• Return an excessively large result set
• Attempt an unauthorized write
• Construct a request that behaves differently across EHR vendors

A stronger architecture exposes narrowly defined business capabilities.

Controlled MCP capability	Permitted function
Retrieve recent laboratory results	Searches approved Observation categories and date ranges for one authorized patient
Get active medications	Returns current medication information from approved FHIR resources
Find documented conditions	Searches Condition resources using defined status and code filters
Validate a clinical code	Confirms the system, code, display, status, version, and value-set membership
Summarize an approved chart section	Retrieves only the resources required for the defined workflow
Prepare a proposed EHR update	Creates a reviewable recommendation without committing a write

The MCP specification requires tools to have defined schemas and emphasizes user control, access protection, tool safety, and consent. It also warns that tool descriptions and behavior should be treated cautiously unless they come from a trusted server.

For healthcare use, each tool should also enforce permitted resource types, fields, patient contexts, date ranges, result limits, and write restrictions at the server level.

Confirm What the EHR Actually Supports

FHIR R4 defines many resources, search parameters, interactions, profiles, and operations. An EHR is not required to implement all of them.

FHIR’s CapabilityStatement resource documents the behavior of an actual or expected FHIR implementation. It can describe the FHIR version, available resources, supported profiles, search parameters, interactions, operations, formats, and security mechanisms.

The integration team should inspect and test the EHR’s CapabilityStatement before publishing MCP tools.

For example, one EHR may support searching laboratory Observations by patient, category, LOINC code, and date. Another may expose a narrower set of search options or depend on vendor-specific extensions.

A production MCP tool catalog should therefore be based on:

• The actual CapabilityStatement
• Vendor implementation documentation
• Sandbox testing
• Search-result validation
• Pagination behavior
• OperationOutcome handling
• Rate-limit testing
• Production configuration differences

The general FHIR specification describes what is possible. The deployed EHR determines what is available.

Why AI Models Hallucinate Clinical Codes in FHIR Workflows 

Clinical codes are not isolated numbers or labels. A FHIR Coding may contain:

• A code-system URI
• A code
• A terminology version
• A display value

FHIR distinguishes between a CodeSystem, which defines available concepts, and a ValueSet, which identifies the codes allowed for a specific context. 

A code may exist in the underlying terminology but still be inappropriate for the FHIR field, implementation guide, payer workflow, or date of service. Common AI coding failures include:

• Returning a real code with the wrong code-system URI
• Producing a plausible but nonexistent code
• Combining a valid code with an incorrect official display
• Selecting an inactive or retired concept
• Using a code that was not active on the relevant date
• Confusing SNOMED CT, ICD-10-CM, LOINC, RxNorm, ICD-10-PCS, and CPT
• Treating an organization’s local code as a standard code
• Selecting a code outside the required value set
• Choosing specificity that the documentation does not support
• Treating a terminology match as proof of coverage or medical necessity

A prompt telling the model not to hallucinate is not a terminology-control strategy. Validation must occur outside the model.

How the Terminology Validation Process Should Work

1. Interpret the Clinical Phrase

The user may provide a phrase such as “elevated A1C,” “long-term insulin use,” or “left knee pain.”

The model can help interpret the request, but it should not create the final code from memory. The FHIR MCP Server should search an approved terminology source and return possible concepts with their official identifiers and descriptions.

When several concepts remain plausible, the workflow should request clarification or route the result for review.

2. Confirm That the Code Exists

FHIR’s CodeSystem/$lookup operation can retrieve authoritative information about a concept, including its preferred display, definition, status, terminology version, designations, and properties.

The operation requires a code and its code-system identifier, or a complete Coding value. It can also support date-specific lookup when historical terminology information is available.

This verifies that the code exists in the selected code system. It does not prove that the code is permitted for the intended workflow.

3. Validate the Code Against the Required Value Set

FHIR’s ValueSet/$validate-code operation evaluates whether a supplied code is valid within a defined value set. The operation can consider:

• Code-system URI
• Code-system version
• Value-set URL
• Value-set version
• Display value
• Effective date

It returns a validation result and can also return warnings, errors, and an authoritative display.

This prevents a technically valid code from being used in a field or workflow where it is not allowed.

4. Evaluate Local Codes and Mappings

Many EHRs contain organization-specific laboratory, medication, problem-list, or order codes.

A FHIR MCP Server should preserve the local code namespace and use a governed mapping repository when translating it to a standard terminology. Similar wording alone does not establish semantic equivalence.

A controlled mapping should record:

• Source and target systems
• Source and target versions
• Mapping relationship
• Mapping author
• Review status
• Effective period
• Known limitations

When no approved mapping exists, the server should return an unresolved result instead of asking the model to infer one.

5. Return Evidence With the Result

A validated terminology result should include enough context to support review. That evidence should identify:

• Code-system URI
• Code
• Official display
• Code-system version
• Value-set URL and version
• Effective date
• Validation result
• Terminology service used
• Source FHIR resource
• Retrieval timestamp
• Relevant warnings
• Human-review requirement

The model can explain this information, but it should not modify or replace the validated terminology result.

6. Fail Closed

If the terminology server is unavailable, the value set cannot be resolved, or the code remains ambiguous, the gateway should return a visible failure.

It should not instruct the model to use its best judgment.

A clear “not validated” result is safer than a confident-looking answer without evidence.

Which Terminologies Matter in US Healthcare?

Terminology	Common US use	Important production control
ICD-10-CM	Diagnosis classification	Use the applicable annual release and date of service
ICD-10-PCS	Inpatient procedure classification	Do not substitute CPT for inpatient procedure coding
SNOMED CT	Detailed clinical concepts	Use the appropriate US Edition and preserve concept status
LOINC	Laboratory tests, observations, measurements, and documents	Validate the full concept rather than only a familiar test name
RxNorm	Normalized clinical drug concepts	Distinguish ingredient, strength, dose form, and packaged concepts
CPT	Professional services and procedures	Use properly licensed authoritative CPT content
Local terminology	Organization-specific concepts	Preserve the namespace and use governed mappings

The National Library of Medicine published the March 2026 SNOMED CT US Edition based on the January 2026 International Edition. NLM also produces RxNorm, which provides normalized clinical drug names and links across commonly used pharmacy vocabularies.

The LOINC FHIR terminology service uses FHIR R4 and supports both current and selected historical versions of terminology resources.

CPT requires additional care. The AMA states that AI-generated output is not authoritative CPT content and that products using or relying on CPT content may require appropriate licensing.

Even a correctly validated code does not establish clinical appropriateness, documentation support, claim sequencing, payer coverage, or medical necessity.

Claude MCP vs Cursor MCP for Healthcare AI –  Use Cases

Claude for Healthcare Workflows

Anthropic introduced Claude for Healthcare in January 2026 with HIPAA-ready product options, healthcare connectors, and FHIR-related development resources. Anthropic describes potential use cases including prior authorization support, claims appeals, care coordination, patient-message triage, and healthcare product development.

Microsoft also announced Claude healthcare and life-sciences capabilities through Microsoft Foundry. Microsoft describes enterprise deployment paths, domain-specific connectors through MCP, specialized skills, and workflows involving prior authorization, claims appeals, care coordination, and patient-message triage.

These announcements do not mean that every Claude configuration is automatically suitable for PHI.

A healthcare organization must verify:

• The exact Anthropic or Microsoft product surface
• The executed BAA
• Feature eligibility
• Data-retention configuration
• Hosting and inference location
• Enabled connectors and tools
• External subprocessors
• Audit and security responsibilities

Anthropic’s current BAA documentation states that eligible Claude Enterprise and first-party API services can be covered under a BAA when the required configuration is in place. However, data sent to third parties through external MCP servers or connectors is not covered by Anthropic’s BAA. Anthropic also states that its direct API MCP connector is not eligible for Zero Data Retention.

That does not automatically prohibit a healthcare MCP deployment. It means the complete data flow must be contractually reviewed. The organization may need appropriate agreements and safeguards covering Anthropic, the MCP operator, the EHR vendor, the terminology provider, the hosting environment, and any monitoring service that handles ePHI.

Cursor for Healthcare Product Engineering

Cursor is primarily an AI coding environment. Its official documentation supports MCP connections to external tools and data sources, allowing engineering teams to connect approved systems to development workflows.

Healthcare engineering teams may use Cursor to:

• Inspect synthetic FHIR resources
• Review CapabilityStatements
• Test FHIR searches
• Validate resources against profiles
• Generate test fixtures
• Investigate OperationOutcome responses
• Build interoperability adapters
• Review terminology mappings
• Diagnose failed conformance tests

Cursor’s security documentation identifies SOC 2 Type II availability, third-party penetration testing, subprocessors, least-privilege infrastructure access, and Privacy Mode controls. Cursor also now provides a process for qualifying Cursor Enterprise customers to request a HIPAA Business Associate Agreement.

A BAA should not be assumed merely because Cursor supports MCP or because an organization uses an Enterprise plan. Production PHI access should occur only after the organization has executed the required agreement, validated the selected configuration, reviewed model and subprocessor data flows, and implemented appropriate workstation, identity, logging, and access controls.

Synthetic or de-identified data should remain the default for ordinary development.

MCP Authorization Does Not Replace SMART on FHIR

A production implementation has at least two authorization boundaries.

The first controls whether the MCP client may call the FHIR MCP Server. The current MCP authorization specification defines OAuth-based authorization for HTTP transports. The MCP server remains responsible for validating access to its own protected tools.

The second boundary controls whether the FHIR MCP Server may access the EHR.

The current published SMART App Launch Implementation Guide is version 2.2.0 and is based on FHIR R4. It defines OAuth-based patterns for integrating applications with FHIR systems, including user-facing app launch and backend-service authorization.

For an interactive workflow, SMART App Launch can provide authenticated user, patient, and encounter context.

For an approved machine-to-machine workflow, SMART Backend Services can authorize a preapproved system client without an interactive user.

The gateway should translate the authenticated MCP identity, role, purpose, patient context, and selected tool into a constrained downstream authorization decision.

An MCP access token should not become a universal EHR credential.

HIPAA and Security Controls for Production

HIPAA does not define a special compliance category for MCP. Covered entities and business associates must still apply appropriate administrative, physical, and technical safeguards to protect the confidentiality, integrity, and availability of ePHI.

Minimum-Necessary Retrieval

Each tool should retrieve only the resources, fields, patients, and date ranges required for the approved purpose. A request for the latest A1C result does not normally require every note, medication, encounter, and historical laboratory result.

HHS states that the minimum necessary standard generally requires covered entities to take reasonable steps to limit PHI use, disclosure, and requests to what is needed for the intended purpose. HHS also identifies exceptions, including certain treatment-related disclosures, so the rule must be applied to the particular use case rather than treated as an absolute restriction.

Prompt-Injection Isolation

Clinical notes, patient messages, scanned documents, and imported text must be treated as untrusted data. Text inside a record must not be allowed to:

• Change access permissions
• Select another patient
• Invoke an additional tool
• Export data
• Override system policy
• Authorize an EHR write

MCP’s specification warns that tools can represent arbitrary operations and that tool descriptions should be considered untrusted unless they come from a controlled server.

Read-Only First

The first production release should normally block create, update, patch, delete, transaction, prescription, order-signing, and billing-submission operations.

Write access should be introduced only after the organization has implemented:

• Explicit human approval
• FHIR profile validation
• Version-conflict handling
• Duplicate prevention
• Idempotency controls
• Rollback or correction workflows
• Downstream reconciliation
• Post-write monitoring

Audit and Provenance

The system should record:

• Who initiated the request
• Which patient or population was accessed
• Which MCP tool was called
• Which FHIR requests were executed
• Which fields were returned
• Which terminology version was used
• Whether code validation passed
• Whether a result was exported or written
• Whether human approval occurred
• Which model and configuration processed the information

Raw PHI, complete FHIR payloads, full prompts, and bearer tokens should not be placed in general application logs.

Vendor and BAA Review

HHS states that a covered entity or business associate may use a cloud service to store or process ePHI when it enters into an appropriate BAA with the provider and otherwise complies with HIPAA. HHS also expects the regulated entity to understand the cloud environment and conduct its own risk analysis.

The review should cover every organization that creates, receives, maintains, or transmits ePHI within the architecture.

Common FHIR MCP Architecture Failures

Exposing the Complete FHIR API

Generic FHIR access gives the model unnecessary control. Tools should represent approved healthcare tasks rather than the complete REST interface.

Retrieving the Whole Patient Record by Default

Broad retrieval increases privacy exposure, latency, context size, and the chance that irrelevant text influences the model. Resource-specific and date-limited queries are safer.

Treating Terminology Validation as Clinical Approval

A terminology service can verify that a code exists and belongs to a value set. It cannot determine whether the documentation supports the code or whether a payer will cover the service.

Ignoring Terminology Versions

Clinical terminologies change. Historical encounters may need to be evaluated against the code and value-set versions applicable on the date of service.

Mapping Codes Through Text Similarity

Local and standard terms can appear similar without being equivalent. Mapping requires governed relationships, version control, and review.

Allowing Silent Fallbacks

When authorization, FHIR retrieval, or terminology validation fails, the system should return a visible failure. It should not replace the missing result with model-generated information.

A Practical FHIR MCP Implementation Plan

Phase 1: Select One Read-Only Use Case

Start with a narrow use case that has measurable value and limited clinical risk.

Suitable first candidates include retrieving recent laboratory results, showing active medications, validating codes in a test workflow, or helping an authorized engineer inspect synthetic FHIR data.

Phase 2: Assess the FHIR Environment

Document the FHIR version, supported resources, profiles, search parameters, SMART configuration, local codes, terminology capabilities, vendor extensions, pagination, rate limits, and error behavior.

Validate the findings through the actual CapabilityStatement and sandbox testing.

Phase 3: Define the Tool and Policy Catalog

For every tool, document:

• Authorized roles
• Approved purpose
• Required patient context
• Resources accessed
• Fields returned
• Result limits
• Terminology dependencies
• Failure behavior
• Audit requirements
• Human-review requirements

Phase 4: Implement Terminology Controls

Connect approved terminology sources and implement concept search, code lookup, value-set validation, terminology versioning, effective-date handling, and governed local-code mappings.

Phase 5: Test Negative and Adversarial Scenarios

Testing should include:

• Unknown and inactive codes
• Correct codes under the wrong system
• Codes outside the required value set
• Incorrect displays
• Ambiguous clinical phrases
• Unsupported FHIR searches
• Duplicate or incorrect patient context
• Expired tokens
• Prompt injection inside clinical text
• Terminology-server outages
• Excessive result requests
• Attempted writes through read-only tools

Phase 6: Pilot With Human Review

Measure retrieval accuracy, terminology-validation success, unauthorized tool attempts, excess-data retrieval, human correction rates, latency, audit completeness, and safe no-result behavior.

Expand the tool catalog only after the first workflow performs reliably under normal, failure, and adversarial conditions.

The Bottom Line

A FHIR MCP Server can give Claude and Cursor a controlled path to EHR data without forcing the model to remember every FHIR search rule, vendor implementation detail, or clinical code.

The reliable architecture combines:

MCP for governed tool invocation, SMART on FHIR for downstream authorization, task-specific FHIR operations for retrieval, authoritative terminology services for validation, policy enforcement for safety, and provenance for accountability.

That architecture does not make the model incapable of being wrong. It prevents unsupported model output from automatically becoming clinical or operational truth.

FHIR MCP Integration Services for Healthcare AI Products

CapMinds helps healthcare SaaS companies, digital health AI teams, and enterprise healthcare innovation groups build the controlled interoperability layer between AI applications and healthcare systems.

Our healthcare product engineering and interoperability services include:

• EHR and FHIR capability assessments
• FHIR MCP gateway architecture and development
• Claude and Cursor MCP integration
• SMART App Launch and Backend Services implementation
• Task-specific FHIR tools and workflow integration
• SNOMED CT, LOINC, RxNorm, ICD-10, CPT, and local-code validation
• Value-set and terminology-service integration
• Patient, tenant, role, and purpose-based access controls
• Audit, provenance, and observability architecture
• Synthetic-data and adversarial testing
• Read-only pilots and controlled production rollout

The result is not simply an AI agent that can reach an EHR.

It is a governed healthcare AI architecture that limits what the agent can access, validates what it returns, records how the result was produced, and prevents unsupported actions from entering production workflows.

Schedule a Healthcare AI Architecture Assessment