fhirhydrant — Claude Code MCP server: install
Connects AI clients to FHIR APIs with tools for resource search, clinical operations, response shaping, and gated writes.
claude mcp add --env MCP_TRANSPORT=<MCP_TRANSPORT> --env FHIR_AUTH=<FHIR_AUTH> --env FHIR_SERVER_URL=<FHIR_SERVER_URL> --env FHIR_TOKEN_URL=<FHIR_TOKEN_URL> --env FHIR_CLIENT_ID=<FHIR_CLIENT_ID> --transport stdio fhirhydrant -- npx -y fhirhydrantWhat fhirhydrant does
fhirhydrant connects MCP clients to FHIR APIs from R4 onward. It exposes configured resource access, named operations, terminology actions, and Bundle pagination as agent tools. JSON files control the resource set, while server metadata and granted SMART scopes determine which actions are available.
The server can search and read resources, inspect history, run configured operations, trim output with FHIRPath, and apply byte limits. Write actions stay disabled until FHIR_WRITE_CAPABILITIES is configured; batch and transaction Bundles need their own capability setting. SMART Backend Services uses a registered client, a signing private key, and a JWKS endpoint for the corresponding public key. Public test endpoints can run with FHIR_AUTH=none.
Node.js >= 24 is required for startup. MCP results may include PHI, so transcript storage and client logging need to match the compliance rules of your environment.
What it helps with
- search FHIR resources with configured parameters
- read a resource version or its change history
- run named clinical and terminology operations
- trim responses with FHIRPath and byte limits
- inspect capabilities and registered tools
Example prompts for the agent
- Search the FHIR server for matching resources and return a compact response.
- Show the change history for this resource ID.
- Inspect the CapabilityStatement and list the operations available to me.
How to install fhirhydrant
Platform CLI
claude mcp add --env MCP_TRANSPORT=<MCP_TRANSPORT> --env FHIR_AUTH=<FHIR_AUTH> --env FHIR_SERVER_URL=<FHIR_SERVER_URL> --env FHIR_TOKEN_URL=<FHIR_TOKEN_URL> --env FHIR_CLIENT_ID=<FHIR_CLIENT_ID> --transport stdio fhirhydrant -- npx -y fhirhydrantReplace <…> with your own values. 3 more environment variables are in the server README
Platform CLI
codex mcp add fhirhydrant --env MCP_TRANSPORT=<MCP_TRANSPORT> --env FHIR_AUTH=<FHIR_AUTH> --env FHIR_SERVER_URL=<FHIR_SERVER_URL> --env FHIR_TOKEN_URL=<FHIR_TOKEN_URL> --env FHIR_CLIENT_ID=<FHIR_CLIENT_ID> -- npx -y fhirhydrantReplace <…> with your own values. 3 more environment variables are in the server README
Config file
{
"mcpServers": {
"fhirhydrant": {
"command": "npx",
"args": [
"-y",
"fhirhydrant"
],
"env": {
"MCP_TRANSPORT": "<MCP_TRANSPORT>",
"FHIR_AUTH": "<FHIR_AUTH>",
"FHIR_SERVER_URL": "<FHIR_SERVER_URL>",
"FHIR_TOKEN_URL": "<FHIR_TOKEN_URL>",
"FHIR_CLIENT_ID": "<FHIR_CLIENT_ID>"
}
}
}
}Replace <…> with your own values. 3 more environment variables are in the server README
Config file
{
"servers": {
"fhirhydrant": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"fhirhydrant"
],
"env": {
"MCP_TRANSPORT": "<MCP_TRANSPORT>",
"FHIR_AUTH": "<FHIR_AUTH>",
"FHIR_SERVER_URL": "<FHIR_SERVER_URL>",
"FHIR_TOKEN_URL": "<FHIR_TOKEN_URL>",
"FHIR_CLIENT_ID": "<FHIR_CLIENT_ID>"
}
}
}
}Replace <…> with your own values. 3 more environment variables are in the server README
Platform CLI
gemini mcp add -e MCP_TRANSPORT=<MCP_TRANSPORT> -e FHIR_AUTH=<FHIR_AUTH> -e FHIR_SERVER_URL=<FHIR_SERVER_URL> -e FHIR_TOKEN_URL=<FHIR_TOKEN_URL> -e FHIR_CLIENT_ID=<FHIR_CLIENT_ID> fhirhydrant npx -y fhirhydrantReplace <…> with your own values. 3 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about fhirhydrant
How do I install fhirhydrant in Claude Code?
Run `claude mcp add fhirhydrant -e MCP_TRANSPORT=<MCP_TRANSPORT> -e FHIR_AUTH=<FHIR_AUTH> -e FHIR_SERVER_URL=<FHIR_SERVER_URL> -e FHIR_ACTIVE_KEY=<FHIR_ACTIVE_KEY> -- npx -y fhirhydrant`.
What does fhirhydrant do?
It exposes FHIR resource access, configured operations, terminology actions, and Bundle pagination to an MCP client. Tool availability follows the server metadata, configuration, and granted SMART scopes.
What is needed for SMART authentication?
You need a supported FHIR server, a SMART Backend Services client registration, a private signing key, and a JWKS endpoint for its public key. An unauthenticated test endpoint can use FHIR_AUTH=none.
