fhir-patient-consent-mcp-server

fhir-patient-consent-mcp-server

An MCP server that lets a model askquestions about a patient, their insulin pump, and who's consented to seethat data - all sourced live from a FHIR (R4) store. No data lives in thisserver; every answer is a real-time FHIR REST query.

It's a companion tofhir-consent-service (a Spring Boot API forwriting Patient/Device/Consent to FHIR), but has no code dependency onit - this server only depends on the FHIR wire format, so it works againstany FHIR R4 endpoint.

Tools

Resource

fhir-chart://{patientId} - a consolidated JSON "chart" (demographics +devices + active consents) for a patient, meant to be attached directlyinto context by a host application rather than assembled by the modelacross several tool calls. See docs/architecture.mdfor why this is a resource rather than a sixth tool.

Setup

npm install
npm run build

Point it at a FHIR server

export FHIR_BASE_URL=http://localhost:8081/fhir   # default shown
export FHIR_AUTH_TOKEN=...                         # optional bearer token

The easiest way to get data to query: runfhir-consent-service's docker compose up -d(starts a local HAPI FHIR JPA server on :8081) and create a patient,device, and consent through its REST API, then query the same store here.

Run it directly (for testing with stdio)

npm run dev

Register it with an MCP client

For Claude Desktop / Claude Code, add to your MCP config:

{
  "mcpServers": {
    "fhir-patient-consent": {
      "command": "node",
      "args": ["/absolute/path/to/fhir-patient-consent-mcp-server/dist/index.js"],
      "env": {
        "FHIR_BASE_URL": "http://localhost:8081/fhir"
      }
    }
  }
}

Run npm run build first so dist/index.js exists.

Example questions once connected

• "Look up the patient with MRN MRN-778001."
• "What insulin pump does patient 123 have, and what's its serial number?"
• "Has GlucoVue Remote Monitoring been given consent to see patient 123's device data?"
• "Show me patient 123's full chart." (exercises the fhir-chart:// resource)

Testing

npm test

Unit tests cover the mapper layer (src/mappers/*.ts), including theconsent-authorization logic in isConsentActiveForPartner - specificallyits handling of revoked consents, not-yet-started/expired periods, andopen-ended (end absent) periods, since those are the cases most likely tobe gotten subtly wrong.

There's no integration test against a live FHIR server in this repo (unlikefhir-consent-service, which uses Testcontainers) because this server hasno write path to seed data with - it would need to depend on that repo (orduplicate its resource-creation logic) purely to set up test fixtures. Ifthis repository grows a seeding script, add one then.

Note: written in a sandboxed environment without npm registry access,so npm install / npm run build / npm test have not actually beenexecuted here. The code targets @modelcontextprotocol/sdk@^1.12; if theSDK's server.tool(...) / server.resource(...) signatures have moved toregisterTool/registerResource by the version you install, the fix ismechanical - check the SDK's own README/CHANGELOG.

Project layout

src/
├── index.ts              Server entry point, registers all tools/resources
├── fhirClient.ts          Thin fetch-based FHIR REST client
├── tools/                 One file per MCP tool
├── resources/             One file per MCP resource
├── mappers/                FHIR JSON -> summary objects + consent auth logic
└── util/results.ts        Shared tool-result formatting helpers

Security note

This server performs no PHI redaction and passes through whatever the FHIRserver returns. If deploying against real patient data, put access controlin front of the FHIR server itself (this server forwards FHIR_AUTH_TOKENas a bearer token, but does not manage token acquisition/refresh) andconsider what should and shouldn't be exposed to an MCP client at all.

License

MIT