Multilingual support: AI agents using these MCP tools can accept queries in any language. The agent translates to English before calling OMOPHub, then presents results in the user’s language. No special configuration needed — just ask in your language.
search_concepts
Search for medical concepts by name or clinical term across all vocabularies.
Parameters
| Parameter | Type | Required | Description |
|---|
query | string | Yes | The medical term or concept name to search for (1–500 characters) |
vocabulary_ids | string | | Comma-separated vocabulary IDs to filter by. Examples: SNOMED, ICD10CM, RxNorm, LOINC |
domain_ids | string | | Comma-separated domain IDs to filter by. Examples: Condition, Drug, Measurement, Procedure |
standard_concept | string | | Filter by standard concept status: S for Standard, C for Classification |
page | number | | Page number, 1-based (default: 1) |
page_size | number | | Results per page, 1–50 (default: 10) |
Example
"Search for metformin in RxNorm"
→ search_concepts(query: "metformin", vocabulary_ids: "RxNorm")
get_concept
Get detailed information about a specific OMOP concept by its numeric ID.
Parameters
| Parameter | Type | Required | Description |
|---|
concept_id | number | Yes | The OMOP concept_id (numeric identifier) |
Example
"What is concept 201826?"
→ get_concept(concept_id: 201826)
get_concept_by_code
Look up a concept using a vocabulary-specific code (e.g., ICD-10 E11.9, SNOMED 44054006).
Parameters
| Parameter | Type | Required | Description |
|---|
vocabulary_id | string | Yes | The vocabulary system. Examples: ICD10CM, SNOMED, RxNorm, LOINC, HCPCS, NDC |
concept_code | string | Yes | The vocabulary-specific code. Examples: E11.9 (ICD-10), 44054006 (SNOMED), 4850 (LOINC) |
Example
"Look up ICD-10 code E11.9"
→ get_concept_by_code(vocabulary_id: "ICD10CM", concept_code: "E11.9")
map_concept
Map a concept to equivalent concepts in other vocabularies (e.g., SNOMED to ICD-10).
Parameters
| Parameter | Type | Required | Description |
|---|
concept_id | number | Yes | The source OMOP concept_id to map from |
target_vocabularies | string | | Comma-separated vocabulary IDs to map to. Examples: ICD10CM, SNOMED, RxNorm |
Example
"Map SNOMED concept 201826 to ICD-10"
→ map_concept(concept_id: 201826, target_vocabularies: "ICD10CM")
get_hierarchy
Navigate concept hierarchy - ancestors, descendants, or both.
Parameters
| Parameter | Type | Required | Description |
|---|
concept_id | number | Yes | The OMOP concept_id |
direction | string | | up for ancestors, down for descendants, both for full context (default: both) |
max_levels | number | | Maximum levels to traverse (default: 5 for up, 10 for down) |
max_results | number | | Maximum nodes to return, 1–500 (default: 500) |
vocabulary_ids | string | | Comma-separated vocabulary IDs to filter results |
Example
"Show me all descendants of Diabetes mellitus"
→ get_hierarchy(concept_id: 201820, direction: "down", max_levels: 3)
list_vocabularies
List available medical vocabularies with statistics.
Parameters
| Parameter | Type | Required | Description |
|---|
search | string | | Optional search term to filter vocabularies by name |
Example
"What vocabularies are available?"
→ list_vocabularies()
"Search for drug vocabularies"
→ list_vocabularies(search: "drug")
semantic_search
Search for medical concepts using natural language with neural embeddings. Unlike keyword search, semantic search understands clinical meaning - “heart attack” finds “Myocardial infarction”, “high blood sugar” finds “Hyperglycemia”.
Parameters
| Parameter | Type | Required | Description |
|---|
query | string | Yes | Natural language description of the medical concept to find (1–500 characters) |
vocabulary_ids | string | | Comma-separated vocabulary IDs to filter by. Examples: SNOMED, ICD10CM, RxNorm |
domain_ids | string | | Comma-separated domain IDs to filter by. Examples: Condition, Drug, Measurement |
standard_concept | string | | Filter by standard concept status: S for Standard, C for Classification |
threshold | number | | Minimum similarity score, 0.0–1.0 (default: 0.5). Higher = stricter matching |
page_size | number | | Results to return, 1–50 (default: 10) |
Example
"Find concepts related to heart attack"
→ semantic_search(query: "heart attack", vocabulary_ids: "SNOMED", threshold: 0.5)
find_similar_concepts
Find medical concepts similar to a reference concept, name, or natural language query. Supports three similarity algorithms. Provide exactly one of: concept_id, concept_name, or query.
Parameters
| Parameter | Type | Required | Description |
|---|
concept_id | number | One of three | Find concepts similar to this OMOP concept ID |
concept_name | string | One of three | Find concepts similar to this concept name |
query | string | One of three | Find concepts matching this natural language description |
algorithm | string | | Similarity algorithm: semantic (meaning), lexical (text), hybrid (both). Default: hybrid |
similarity_threshold | number | | Minimum similarity score, 0.0–1.0 (default: 0.7) |
page_size | number | | Results to return, 1–100 (default: 20) |
vocabulary_ids | string | | Comma-separated vocabulary IDs to filter results |
domain_ids | string | | Comma-separated domain IDs to filter results |
Example
"What concepts are similar to Type 2 diabetes?"
→ find_similar_concepts(concept_name: "Type 2 diabetes mellitus", algorithm: "hybrid")
explore_concept
Get a comprehensive view of a medical concept in one call: detailed info, ancestors/descendants hierarchy, and cross-vocabulary mappings. Use this instead of calling get_concept + get_hierarchy + map_concept separately.
Parameters
| Parameter | Type | Required | Description |
|---|
concept_id | number | Yes | The OMOP concept_id to explore |
include_hierarchy | boolean | | Include ancestors and descendants (default: true) |
hierarchy_levels | number | | How many hierarchy levels to fetch, 1–5 (default: 2) |
include_mappings | boolean | | Include cross-vocabulary mappings (default: true) |
target_vocabularies | string | | Comma-separated vocabulary IDs to filter mappings. Examples: ICD10CM, SNOMED |
Example
"Give me everything about SNOMED concept 201826"
→ explore_concept(concept_id: 201826)
"Show concept 201826 with ICD-10 mappings only"
→ explore_concept(concept_id: 201826, target_vocabularies: "ICD10CM")
fhir_resolve
Resolve a FHIR coded value (system URI + code) to its OMOP standard concept, CDM target table, and optional Phoebe recommendations. Supports text-only input via semantic search fallback.
Parameters
| Parameter | Type | Required | Description |
|---|
system | string | | FHIR code system URI (e.g. http://snomed.info/sct, http://loinc.org) |
code | string | | Code value from the FHIR Coding |
display | string | | Display text for semantic search fallback when code is unavailable |
vocabulary_id | string | | Direct OMOP vocabulary_id (e.g. SNOMED, ICD10CM), bypasses URI resolution |
resource_type | string | | FHIR resource type (Condition, Observation, MedicationRequest, Procedure, etc.) |
include_recommendations | boolean | | Include Phoebe-recommended related concepts (default: false) |
include_quality | boolean | | Include mapping quality signal: high, medium, low, or manual_review (default: false) |
system + code), (vocabulary_id + code), or display is required.
Example
"What OMOP concept does SNOMED 44054006 map to?"
→ fhir_resolve(system: "http://snomed.info/sct", code: "44054006", resource_type: "Condition")
"Resolve this ICD-10 code to OMOP with quality signal"
→ fhir_resolve(system: "http://hl7.org/fhir/sid/icd-10-cm", code: "E11.9", include_quality: true)
"Find the OMOP concept for 'heart attack' using semantic search"
→ fhir_resolve(display: "heart attack", resource_type: "Condition")
fhir_resolve_codeable_concept
Resolve a FHIR CodeableConcept with multiple codings. Picks the best match per OHDSI vocabulary preference (SNOMED > RxNorm > LOINC > CVX > ICD-10). Falls back to the text field via semantic search if no coding resolves.
Parameters
| Parameter | Type | Required | Description |
|---|
coding | array | Yes | Array of FHIR Coding entries (max 20). Each with system, code, and optional display |
text | string | | CodeableConcept.text for semantic search fallback if no coding resolves |
resource_type | string | | FHIR resource type for domain alignment |
include_recommendations | boolean | | Include Phoebe recommendations (default: false) |
include_quality | boolean | | Include mapping quality signal (default: false) |
Example
"Which coding should I use from this CodeableConcept with SNOMED and ICD-10?"
→ fhir_resolve_codeable_concept(
coding: [
{system: "http://snomed.info/sct", code: "44054006"},
{system: "http://hl7.org/fhir/sid/icd-10-cm", code: "E11.9"}
],
resource_type: "Condition"
)
