MCP tools reference for OMOPHub vocabularies

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: `semantic`
`similarity_threshold`	number		Minimum similarity score, 0.0–1.0 (default: `0.7`). `0` is valid and honoured
`page`	number		Page of the ranked candidate pool, 1-based (default: `1`)
`page_size`	number		Results to return, 1–1000 (default: `20`)
`vocabulary_ids`	string		Comma-separated vocabulary IDs to filter results
`domain_ids`	string		Comma-separated domain IDs to filter results
`concept_class_ids`	string		Comma-separated concept class IDs to filter results
`include_explanations`	boolean		Add a short explanation of why each concept matched (default: `false`)

Pagination

The tool’s text output ends with the position in the ranking — Page 2 of 3 — more results available, request page 3. — and the JSON block carries the full pagination object. Page while has_next is true rather than comparing page to total_pages. Every algorithm ranks a bounded candidate pool and total_candidates counts only what cleared the threshold inside it, so the totals can be lower bounds; search_metadata.totals_are_lower_bound says when. Reachable depth is bounded at roughly 500 / page_size pages — the pool is a constant 500 candidates, so a score never changes with page_size — and a page past the end comes back empty with has_next: false rather than as an error. hybrid fuses both signals as 0.7 x semantic + 0.3 x lexical. Every candidate is scored by that rule, with a signal neither retrieval established counting as 0. So a concept sharing no words with the query keeps only 0.7 x its semantic score, and one the embedding search did not return keeps only 0.3 x its lexical score — capping it at 0.3. The same similarity_threshold is therefore stricter for hybrid than for either single-signal algorithm. Lower it, use semantic for conceptual matches that share no vocabulary, or use lexical for exact name and code matches: hybrid is not a superset of the other two. When hybrid is requested but the embedding service is unavailable, the tool serves the lexical half and says so, reporting algorithm_used: "lexical" with degraded_from: "hybrid".

Example

"What concepts are similar to Type 2 diabetes?"
→ find_similar_concepts(concept_name: "Type 2 diabetes mellitus")

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	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`)

At least one of (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"
  )

Get Started

MCP Server

Docs for Agents

Integration

MCP tools reference for OMOPHub vocabularies

search_concepts

Parameters

Example

get_concept

Parameters

Example

get_concept_by_code

Parameters

Example

map_concept

Parameters

Example

get_hierarchy

Parameters

Example

list_vocabularies

Parameters

Example

semantic_search

Parameters

Example

find_similar_concepts

Parameters

Example

explore_concept

Parameters

Example

fhir_resolve

Parameters

Example

fhir_resolve_codeable_concept

Parameters

Example

​search_concepts

​Parameters

​Example

​get_concept

​Parameters

​Example

​get_concept_by_code

​Parameters

​Example

​map_concept

​Parameters

​Example

​get_hierarchy

​Parameters

​Example

​list_vocabularies

​Parameters

​Example

​semantic_search

​Parameters

​Example

​find_similar_concepts

​Parameters

​Pagination

​Example

​explore_concept

​Parameters

​Example

​fhir_resolve

​Parameters

​Example

​fhir_resolve_codeable_concept

​Parameters

​Example

search_concepts

Parameters

Example

get_concept

Parameters

Example

get_concept_by_code

Parameters

Example

map_concept

Parameters

Example

get_hierarchy

Parameters

Example

list_vocabularies

Parameters

Example

semantic_search

Parameters

Example

find_similar_concepts

Parameters

Pagination

Example

explore_concept

Parameters

Example

fhir_resolve

Parameters

Example

fhir_resolve_codeable_concept

Parameters

Example