> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omophub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools reference for OMOPHub vocabularies

> Complete parameter reference for all 11 OMOPHub MCP tools: search, mapping, hierarchy, FHIR resolve, and vocabulary lookup for AI clients.

> [!TIP]
>
> **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–200 (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` |
| `page` | number | | Page number, 1-based (default: `1`) |
| `page_size` | number | | Mappings per page, 1–200 (default: `100`) |

### Example

```
"Map SNOMED concept 201826 to ICD-10"
→ map_concept(concept_id: 201826, target_vocabularies: "ICD10CM")
```

To map a source code, look up its source OMOP ID first, then pass that returned ID to `map_concept`:

```
"Map ICD-10-CM E11.9 to a standard SNOMED concept"
→ get_concept_by_code(vocabulary_id: "ICD10CM", concept_code: "E11.9")
  Source concept_id: 35206882
→ map_concept(concept_id: 35206882, target_vocabularies: "SNOMED")
  Maps to: Type 2 diabetes mellitus (concept_id: 201826)
```

This example was verified against hosted MCP 1.6.3 and vocabulary release 2026.2 on 17 October 2026. The source ID and standard target ID are different. For complete mapping lists, check `has_more` and request subsequent pages until it is `false`.

***

## 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–200 (default: `200`) |
| `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 | 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`) |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.