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

# OMOPHub MCP Server for Claude, Cursor, and VS Code

> Install the OMOPHub MCP Server to give Claude, Cursor, VS Code, and other AI clients direct access to OMOP medical vocabularies and concept search.

## What is the MCP Server?

The OMOPHub MCP Server connects your AI assistant to the entire OHDSI ATHENA vocabulary. No database setup, no CSV wrangling - just ask your AI about medical concepts and get verified answers.

```
You: "Map ICD-10 code E11.9 to SNOMED"

Claude: Found it - E11.9 (Type 2 diabetes mellitus without complications)
        maps to SNOMED concept 201826 (Type 2 diabetes mellitus)
        via standard 'Maps to' relationship.
```

<Card title="Hosted MCP - No Installation Required" icon="cloud" href="/ai/mcp-hosted">
  Skip installation entirely. Connect your AI client directly to mcp.omophub.com with just your API key.
</Card>

## Installation

Install via npm - no build step required:

```bash theme={null}
npm install -g @omophub/omophub-mcp
```

Or run directly with `npx`:

```bash theme={null}
npx -y @omophub/omophub-mcp
```

### Claude Desktop

Open Claude Desktop settings > **Developer** tab > **Edit Config**. Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "omophub": {
      "command": "npx",
      "args": ["-y", "@omophub/omophub-mcp"],
      "env": {
        "OMOPHUB_API_KEY": "oh_your_key_here"
      }
    }
  }
}
```

### Claude Code

```bash theme={null}
claude mcp add omophub -- npx -y @omophub/omophub-mcp
# Then set OMOPHUB_API_KEY in your environment
```

### Cursor

Open the command palette > **Cursor Settings** > **MCP** > **Add new global MCP server**. Add to `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "omophub": {
      "command": "npx",
      "args": ["-y", "@omophub/omophub-mcp"],
      "env": {
        "OMOPHUB_API_KEY": "oh_your_key_here"
      }
    }
  }
}
```

### VS Code

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "servers": {
    "omophub": {
      "command": "npx",
      "args": ["-y", "@omophub/omophub-mcp"],
      "env": {
        "OMOPHUB_API_KEY": "oh_your_key_here"
      }
    }
  }
}
```

### Windsurf

Add to your Windsurf MCP configuration:

```json theme={null}
{
  "mcpServers": {
    "omophub": {
      "command": "npx",
      "args": ["-y", "@omophub/omophub-mcp"],
      "env": {
        "OMOPHUB_API_KEY": "oh_your_key_here"
      }
    }
  }
}
```

## Available Tools

| Tool                    | Description                                                                         |
| :---------------------- | :---------------------------------------------------------------------------------- |
| `search_concepts`       | Search for medical concepts by name or clinical term across all vocabularies        |
| `get_concept`           | Get detailed info about a specific OMOP concept by `concept_id`                     |
| `get_concept_by_code`   | Look up a concept using a vocabulary-specific code (e.g., ICD-10 `E11.9`)           |
| `map_concept`           | Map a concept to equivalent concepts in other vocabularies                          |
| `get_hierarchy`         | Navigate concept hierarchy - ancestors, descendants, or both                        |
| `list_vocabularies`     | List available medical vocabularies with statistics                                 |
| `semantic_search`       | Search using natural language with neural embeddings - understands clinical meaning |
| `find_similar_concepts` | Find concepts similar to a reference concept, name, or description                  |
| `explore_concept`       | Get concept details, hierarchy, and cross-vocabulary mappings in one call           |

<Card title="Tools Reference" icon="wrench" href="/ai/mcp-tools">
  See detailed parameter schemas and examples for each tool.
</Card>

## Environment Variables

| Variable                   | Required | Description                                                    |
| :------------------------- | :------: | :------------------------------------------------------------- |
| `OMOPHUB_API_KEY`          |    Yes   | Your OMOPHub API key                                           |
| `OMOPHUB_BASE_URL`         |          | Custom API base URL (default: `https://api.omophub.com/v1`)    |
| `OMOPHUB_LOG_LEVEL`        |          | `debug` · `info` · `warn` · `error` (default: `info`)          |
| `OMOPHUB_ANALYTICS_OPTOUT` |          | Set to `true` to disable analytics headers                     |
| `MCP_TRANSPORT`            |          | `stdio` (default) or `http`                                    |
| `MCP_PORT`                 |          | HTTP server port (default: `3100`, only with `http` transport) |
| `HEALTH_PORT`              |          | Port for standalone health endpoint in stdio mode              |

## Example Prompts

Try these after installing:

> "What's the OMOP concept ID for type 2 diabetes?"

> "Map ICD-10 code E11.9 to SNOMED"

> "Show me all descendants of Diabetes mellitus in SNOMED"

> "Search for metformin in RxNorm"

> "Help me build a concept set for heart failure including all descendants"

> "Find concepts related to 'heart attack'" *(uses semantic search)*

> "Give me everything about SNOMED concept 201826" *(uses explore)*

> "What concepts are similar to 'Type 2 diabetes mellitus'?"

## Troubleshooting

| Error                   | Solution                                                                                              |
| :---------------------- | :---------------------------------------------------------------------------------------------------- |
| `API key required`      | Set `OMOPHUB_API_KEY` in your environment or MCP config                                               |
| `Authentication failed` | API key may be invalid or expired - [generate a new one](https://dashboard.omophub.com)               |
| `Rate limit exceeded`   | Automatic retries are built in. For higher limits, [upgrade your plan](https://dashboard.omophub.com) |
| Tools not appearing     | Restart your AI client, verify `npx @omophub/omophub-mcp` runs without errors                         |