Overview

The OMOP MCP Server is a lightweight service that uses large language models (LLMs) to map clinical text and terminology to standardized OMOP (Observational Medical Outcomes Partnership) concept identifiers. By combining a Model Context Protocol (MCP) orchestration layer with configurable LLM backends, the server helps teams convert heterogeneous clinical inputs—ICD codes, free-text diagnoses, medication names, lab descriptions—into a consistent OMOP vocabulary. This standardization is a key step for building research-ready healthcare datasets, cohort definitions, and analytics pipelines.

Designed for developers and data engineers, the server acts as an intermediary: you send clinical terms or free text, it generates candidate mappings (concept IDs and names), and returns structured results suitable for downstream ingestion, validation, or review. The system is useful for accelerating ETL tasks, improving data interoperability, and adding semi-automated concept normalization to clinical data workflows.

Features

LLM-driven mapping: use configurable LLM providers to generate candidate OMOP concept mappings from text.
API-first design: REST endpoints for single or batch mapping requests, health checks, and concept lookup.
Configurable prompts and model selection via environment variables or a config file.
Support for batch processing for ETL workflows and dataset harmonization.
Minimal deployment options: run locally, with Docker, or inside containerized orchestration.
Audit-friendly responses: return candidate concepts, confidence signals, and the model prompt used for reproducibility.
Extensible: add custom prompt templates or integrate alternative LLM providers.

Installation / Configuration

Clone the repository and install dependencies (Python 3.8+ recommended):

git clone https://github.com/OHNLP/omop_mcp.git
cd omop_mcp
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run the server locally (example using Uvicorn / FastAPI):

# assuming app is exposed as app:app in the project
uvicorn app:app --host 0.0.0.0 --port 8080

Environment variables (example .env):

# LLM provider credentials
OPENAI_API_KEY=sk-...

# Optional: provider and model settings
MODEL_PROVIDER=openai
MODEL_NAME=gpt-4o-mini

# Server options
PORT=8080

# OMOP / behavior settings
DEFAULT_VOCABULARY=SNOMED
PROMPT_TEMPLATES_DIR=./prompts

Docker (build and run):

docker build -t omop-mcp:latest .
docker run -e OPENAI_API_KEY="$OPENAI_API_KEY" -p 8080:8080 omop-mcp:latest

Configuration is typically driven by environment variables or a YAML/JSON config file for prompts, model selection, and mapping policies.

Available Resources

API endpoints (examples)

Endpoint	Method	Description
/health	GET	Health check / readiness
/map	POST	Map a single term or text to OMOP concepts
/batch_map	POST	Submit a batch of items for mapping
/concept/{id}	GET	Retrieve concept metadata (if stored/cached)
/prompts	GET/POST	List or update prompt templates (admin)

Sample single-map request:

POST /map
Content-Type: application/json

{
  "text": "Type II diabetes mellitus without complications",
  "source": "free_text",
  "max_candidates": 3
}

Sample response (abbreviated):

{
  "input": "Type II diabetes mellitus without complications",
  "candidates": [
    {"concept_id": 201820, "concept_name": "Type 2 diabetes mellitus", "rank": 1, "score": 0.92},
    {"concept_id": 433144, "concept_name": "Adult onset diabetes", "rank": 2, "score": 0.74}
  ],
  "prompt_used": "Map the following clinical phrase to OMOP concepts..."
}

Code examples and sample prompts live in the repository under prompts/ and examples/.

Use Cases

Clinical ETL normalization: map diagnosis and procedure fields from EHR exports to OMOP concept IDs during ingestion to standardize diverse source terminologies.
Free-text coding assistance: convert clinician notes or problem lists into candidate OMOP concepts for human review and fast curation.
Medication reconciliation: normalize medication names and formulations to standard RxNorm/ATC concepts for pharmacoepidemiology studies.
Cohort building: transform inclusion/exclusion criteria written in natural language into sets of OMOP concepts to seed cohort logic and concept sets.
Quality assurance and reconciliation: compare existing coded concepts against LLM-suggested alternatives to find potential miscoding or gaps in mapping.

Best Practices and Notes

Treat LLM outputs as candidate mappings. Use human review, rule-based filters, or validation against vocabularies before committing mappings to authoritative datasets.
Monitor and log prompts, model versions, and confidence scores to support reproducibility and audits.
Ensure PHI is handled according to your organization’s policies—avoid sending identifiable patient data to third-party LLM endpoints unless authorized.
Start with small batches and evaluate precision/recall for your clinical domain before scaling to full ETL runs.

Resources

GitHub repository: https://github.com/OHNLP/omop_mcp — source code, examples, and prompt templates
Repository README and examples contain additional deployment scenarios and integration tips.

OMOP MCP Server: LLM Mapping to OMOP Concepts