> ## 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.
</Tip>

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

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