Azure AHDS FHIR

Azure AHDS FHIR MCP Server provides a standardized MCP interface to interact with Azure Health Data Services FHIR servers, enabling you to perform common healthcare data operations through MCP tools and protocols.

How to use

You interact with the MCP server using MCP clients or tooling that communicates via the MCP protocol. This server exposes standard FHIR resources (such as Patient, Observation, Medication, and more) through the MCP interface, allowing you to search, retrieve, and manage healthcare data from your Azure FHIR instance. Use the HTTP MCP endpoint for remote access or the local stdio transport if you run the MCP server as a local process. When authentication is configured, you can use either client credentials for service-to-service calls or an on-behalf-of flow to obtain user-scoped access tokens. Ensure your FHIR base URL, application credentials, and tenant information are correctly provided in the environment configuration before starting the server.

Typical usage patterns include: - Searching for FHIR resources by parameters (e.g., patients by name or identifiers) through the MCP interface. - Accessing a specific resource by its type and ID (e.g., fhir://Patient/{id}). - Enumerating resources of a given type (e.g., fhir://Observation/ for observations). - Retrieving the current user information when using OAuth-based authentication (get_user_info). - Integrating with your healthcare data workflows by connecting your MCP client to the appropriate transport (http for remote access or stdio for local execution).

How to install

# Prerequisites
# Ensure Python 3.13+ is installed
# Install the uv runtime if not already available in your environment
# Then follow the steps below to set up and run the MCP server

# 1) Install dependencies and install the MCP package in editable mode
uv pip install -e .

# 2) Run the MCP server locally using stdio transport (example for Azure FHIR MCP Server)
uv run --env-file .env azure-fhir-mcp-server

If you prefer the HTTP transport (remote MCP URL), you expose the MCP endpoint at the configured URL and point your MCP client to it. The following configuration shows how to set up an HTTP-based MCP server entry that connects to a local MCP proxy endpoint.

Configuration and security

Two authentication approaches are supported: a client credentials flow for service-to-service authentication and an OAuth on-behalf-of flow for user-scoped access. The client credentials flow runs without the OAuth proxy, while the on-behalf-of flow uses the FastMCP OAuth proxy to obtain tokens. When using the OAuth proxy, you must enable the proxy, set the HTTP transport, and configure the proxy’s callback path.

Environment variables shown in the configuration include the FHIR base URL, Azure AD client ID, client secret, and tenant ID. For the OAuth flow, additional proxy-related settings control the proxy base URL, redirect path, and requested scopes. Ensure you provide values for all required variables in your .env file before starting the server.

Troubleshooting notes

If you encounter authentication issues, verify that your Azure AD app registration has the correct API permissions and that the redirect URI matches your proxy configuration. Check that the FHIR base URL is reachable and that the MCP server process has the necessary environment variables defined. Review logs at the configured LOG_LEVEL to diagnose connectivity or token issues. If the HTTP endpoint is not reachable, confirm that the port is open and the proxy is correctly forwarding requests to the MCP server.

Available tools

search_fhir

Search for FHIR resources based on a dictionary of search parameters.

get_user_info

(OAuth only) Return information about the authenticated Azure user.