HAPI

You have a healthcare-focused MCP server that exposes FHIR-based patient data through easy-to-call tools. It lets you retrieve patient details, medication requests, and observations by patient ID or name, enabling AI-assisted querying in clinical workflows.

How to use

You will run the MCP server alongside your MCP host (such as Cline) and invoke its tools from your client. The server connects to a FHIR API and returns JSON data for common healthcare queries. Use the tools to:

• Find a patient by ID to get detailed demographics and records
• Find medication requests by patient ID to review prescribed therapies
• Find observations by patient ID to access vitals and lab results
• Find patients by name to locate matching records quickly When you ask your MCP host to perform a task, it will route the request to the MCP server, which queries the FHIR API and returns structured results you can feed into downstream apps or AI prompts.

How to install

Prerequisites you need before installing:

• Python 3.8+ installed on your system
• Access to a terminal or command prompt
• Basic familiarity with creating a virtual environment and installing Python packages Steps to install and run the HAPI MCP server locally:

1. Clone the project repository
2. Create a virtual environment and activate it
3. Install dependencies
4. Run the MCP server script to start listening for tool calls

git clone <repository_url>
cd <repository_directory>

python3 -m venv venv
source venv/bin/activate

pip install -r requirements.txt

# Start the MCP server (example command shown in the provided snippet)
python hapi-mcp-server.py

# The server should now be available to your MCP host for tool calls

Additional content

Configuration, security considerations, and example usage are described below. You’ll configure the MCP host to point to the HAPI MCP server via a local stdio transport that runs the Python script within a virtual environment. The HAPI MCP server uses a FHIR base URL to query data, which you set in the environment when you start the server.

Note on architecture: a user sends a natural language query to the MCP host. The host delegates the request to the MCP server, which makes HTTP requests to the FHIR API, retrieves data, and returns JSON results to the host, which then presents the information to you.

If you need to add the HAPI MCP server to your MCP host configuration, you’ll typically place a configuration entry under the MCP server definitions. An example configuration object is shown here.

{
  "hapi-mcp-server": {
    "command": "/path/to/server/hapi_mcp/venv/bin/python",
    "args": [
      "/path/to/server/hapi_mcp/hapi-mcp-server.py"
    ],
    "env": {
      "HAPI_MCP_SERVER_HOST": "https://hapi.fhir.org/baseR4"
    },
    "description": "Returns a patient FHIR resources for a given patient ID"
  }
}

Security and notes

Secure your MCP setup by restricting access to the MCP host and ensuring the FHIR API endpoint requires proper authorization. Use environment variables to store sensitive URLs and tokens, and rotate credentials regularly.

If you encounter issues starting the server, verify that the Python virtual environment is activated, dependencies are installed, and the hapi-mcp-server.py script is present at the expected path. Confirm that the FHIR base URL is reachable and that network policies allow outbound requests to the FHIR service.

Architecture diagram

In practice, the flow is: User issues a natural language query → MCP Host (e.g., Cline) forwards to MCP Server → MCP Server queries the FHIR API → FHIR API returns data → MCP Server sends results back to the MCP Host → User receives processed information.

Available tools

find_patient

Retrieves detailed patient information by a unique patient identifier using the FHIR Patient endpoint.

find_medication_requests_by_patient_id

Fetches all medication requests for a given patient ID from the FHIR server.

find_observations_by_patient_id

Retrieves observations, such as vitals or labs, for a specific patient ID.

find_patient_by_name

Searches for patients by first and last name and returns a list of matches.