1upHealth MCP Server

A Model Context Protocol (MCP) server for integrating with the 1upHealth FHIR API. This server provides comprehensive access to healthcare data through standardized FHIR resources.

Features

🏥 Patient Search & Management

• Search patients by name, identifier, birth date, or gender
• Retrieve individual patient records
• Support for FHIR-compliant patient data formats

🔬 Clinical Data Access

• Comprehensive clinical data retrieval using FHIR $everything operation
• Observations (lab results, vital signs, diagnostics)
• Conditions and diagnoses
• Medication requests and prescriptions
• Procedures and treatments
• Clinical summaries with resource counts and recent activity

🔧 Advanced FHIR Operations

• Flexible FHIR resource queries with custom parameters
• Support for _include and _revinclude operations
• Date range searches and filtering
• LOINC code-based searches

Installation

1. **Install node&npm

2. Install Dependencies

   npm install

3. Environment Configuration

   cp .env.example .env

   Edit .env with your 1upHealth credentials:

   ONEUP_BASE_URL=https://api.1up.health
   MCP_SERVER_NAME=1uphealth-mcp-server
   MCP_SERVER_VERSION=1.0.0
   PORT=3000
   FHIR_VERSION=r4

4. Build the Project

   npm run build

Usage

Development Mode (with auto-reload)

npm run dev

Production Mode

npm start

Authentication

This server uses stateless authentication with Authorization Bearer headers. When connecting to the MCP server, provide your 1upHealth access token in the Authorization header:

Authorization: Bearer your_access_token_here

The server operates in HTTP-only mode and expects clients to provide valid access tokens at connection time.

Available Tools

Patient Operations

search-patients

Search for patients using various criteria.

Parameters:

• query (optional): Name, identifier, or other search terms
• identifier (optional): System|value format (e.g., "http://hospital.org/mrn|12345")
• family (optional): Last name
• given (optional): First name
• birthdate (optional): Birth date in YYYY-MM-DD format
• gender (optional): male | female | other | unknown
• _count (optional): Number of results (1-100, default: 10)

Example:

{
  "name": "search-patients",
  "arguments": {
    "query": "John Smith",
    "_count": 20
  }
}

get-patient

Get a specific patient by ID.

Parameters:

• patient_id (required): FHIR Patient resource ID

Clinical Data Operations

get-clinical-data

Retrieve comprehensive clinical data for a patient.

Parameters:

• patient_id (required): FHIR Patient resource ID
• resource_types (optional): Array of specific resource types
• since (optional): ISO date for modified after filter
• start_date (optional): Clinical date range start
• end_date (optional): Clinical date range end

get-observations

Get observations for a patient.

Parameters:

• patient_id (required): FHIR Patient resource ID
• code (optional): LOINC or other observation code
• category (optional): laboratory | vital-signs | etc.
• since (optional): ISO date filter
• count (optional): Number of results (default: 50)

get-conditions

Get conditions/diagnoses for a patient.

get-medications

Get medication requests for a patient.

get-clinical-summary

Get comprehensive clinical summary with resource counts.

FHIR Operations

query-fhir

Execute flexible FHIR queries.

Parameters:

• resource_type (required): FHIR resource type
• parameters (required): Key-value pairs for FHIR search parameters
• include (optional): Array of _include parameters
• count (optional): Number of results (default: 10)

Architecture

Project Structure

src/
├── config/              # Environment configuration
│   └── environment.ts
├── services/            # API client services
│   └── oneup-client.ts
├── tools/               # MCP tool implementations
│   ├── patient-tools.ts
│   ├── clinical-tools.ts
│   └── fhir-tools.ts
├── types/               # TypeScript type definitions
│   ├── fhir.ts
│   └── tools.ts
├── utils/               # Utility functions
│   ├── errors.ts
│   ├── http.ts
│   └── fhir.ts
└── server.ts            # Main MCP server

Key Design Principles

1. Stateless HTTP Transport: Designed for stateless operation using Authorization Bearer headers
2. Modular Architecture: Separate modules for different functional areas
3. Type Safety: Comprehensive TypeScript types for all API interactions
4. Error Handling: Robust error handling with specific error types
5. FHIR Compliance: Full adherence to FHIR R4 standards
6. Security: Token-based authentication with HTTPS communication

Authentication Flow

1. Client Connection: Client connects with Authorization Bearer header containing valid 1upHealth access token
2. Token Validation: Server extracts and uses the provided access token for API calls
3. API Access: Direct API access using the client-provided token
4. Stateless Operation: No server-side token storage or session management

Error Handling

The server implements comprehensive error handling:

• AuthenticationError: Authentication failures
• ValidationError: Input validation failures
• NotFoundError: Resource not found
• ApiError: General API errors

Development

Scripts

• npm build: Build TypeScript to JavaScript
• npm run dev: Development mode with auto-reload
• npm start: Start production server

Environment Variables

See .env.example for all available configuration options.

Testing

The server can be tested using Claude Desktop or any MCP-compatible client by providing a valid 1upHealth access token in the Authorization header.

API Reference

1upHealth API Integration

This server integrates with the following 1upHealth APIs:

• FHIR R4 API: Clinical data access
• Bulk Export API: Population-level data export

FHIR Version Support

• Configurable FHIR version support (R4 or DSTU2)
• Set FHIR_VERSION=r4 or FHIR_VERSION=dstu2 in your environment

FHIR Resource Support

• Patient, Observation, Condition, MedicationRequest
• Procedure, DiagnosticReport, DocumentReference
• Encounter, AllergyIntolerance, Immunization
• And all other FHIR R4/DSTU2 resources