How to give an AI agent or LLM access to SNOMED CT and LOINC codes

Connect the agent to a terminology server through MCP so it can look up codes and verify its answers. OMOPHub gives your client 11 tools across 120+ OHDSI ATHENA vocabularies, including SNOMED CT, LOINC, ICD-10, and RxNorm.

One connection. Real vocabulary records.

Hosted endpoint
https://mcp.omophub.com
Authentication
Your OMOPHub API key
Local package
@omophub/omophub-mcp

The hosted server needs no local installation. Claude Desktop can use the local stdio package. Both retrieve vocabulary data from OMOPHub.

Give the model a lookup, not another code to memorize.

A plausible code is not a verified code. An MCP tool lets the agent retrieve the vocabulary record, inspect its source code and OMOP concept ID, and follow published mappings. Your application can check those structured results before using them.

Tools ground the lookup; the model can still choose an inappropriate concept. Keep clinical context and human review in your workflow.

Set up your agent in two steps

1. Get an API key

Create an account, then generate a key in API Keys. The free plan includes 3,000 API calls per month. MCP tools use your API plan and quotas.

2. Add the configuration for your client

Replace the placeholder with your key, or set OMOPHUB_API_KEY for Codex and VS Code. Keep real keys in personal configuration or a secret store; do not commit them to a repository.

Claude Code

Run in your terminal

Register the hosted server, then run /mcp inside Claude Code to check the connection.

bash
claude mcp add omophub --transport http \
  --header "Authorization: Bearer oh_your_key_here" \
  https://mcp.omophub.com

Setup reference for Claude Code

Codex / ChatGPT desktop

~/.codex/config.toml

Set OMOPHUB_API_KEY in the environment that launches your client. This configuration works with the Codex CLI, the IDE extension, and ChatGPT desktop on a local Codex host. Restart the client and check its MCP server list for omophub.

toml
[mcp_servers.omophub]
url = "https://mcp.omophub.com"
bearer_token_env_var = "OMOPHUB_API_KEY"

Setup reference for Codex / ChatGPT desktop

Cursor / Windsurf

Cursor: ~/.cursor/mcp.json · Windsurf: ~/.codeium/windsurf/mcp_config.json

Add the server to your personal MCP configuration. Enable it in the client and check that its tools appear.

json
{
  "mcpServers": {
    "omophub": {
      "url": "https://mcp.omophub.com",
      "headers": {
        "Authorization": "Bearer oh_your_key_here"
      }
    }
  }
}

Setup reference for Cursor / Windsurf

VS Code

.vscode/mcp.json

Set OMOPHUB_API_KEY in the environment that starts VS Code. Run MCP: List Servers and start omophub.

json
{
  "servers": {
    "omophub": {
      "type": "http",
      "url": "https://mcp.omophub.com",
      "headers": {
        "Authorization": "Bearer ${env:OMOPHUB_API_KEY}"
      }
    }
  }
}

Setup reference for VS Code

Claude Desktop

claude_desktop_config.json

Use the local stdio package with Node.js and npx installed, then fully restart Claude Desktop. Vocabulary requests still go to the OMOPHub API.

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

Setup reference for Claude Desktop

Check the connection with a terminology question

Confirm that the client lists OMOPHub’s tools, then ask it to use them explicitly:

  • “Look up SNOMED CT code 44054006. Show its source code, name, and OMOP concept ID.”
  • “Find LOINC concepts for hemoglobin A1c. Show the returned codes and displays so I can compare them.”
  • “Look up ICD-10-CM E11.9, then retrieve its mappings to SNOMED.”

For code lookup, supply both the vocabulary and source code. For mapping, pass the returned OMOP concept_id to map_concept. Ask for results from tool responses and review the actual records.

The 11 MCP tools

Version 1.6.3 source

Use the tool reference for parameters, pagination, and examples.

search_concepts
Search concepts by name or clinical term.
get_concept
Retrieve an OMOP concept by its concept_id.
get_concept_by_code
Look up a source code within a named vocabulary.
map_concept
Retrieve cross-vocabulary mappings, with pagination.
get_hierarchy
Explore ancestors, descendants, or both.
list_vocabularies
Browse available vocabularies and their statistics.
semantic_search
Find concepts using English natural-language queries.
find_similar_concepts
Find concepts related to a reference concept.
explore_concept
Get concept details, hierarchy, and mappings together.
fhir_resolve
Resolve a FHIR Coding to an OMOP standard concept and CDM target table.
fhir_resolve_codeable_concept
Resolve a FHIR CodeableConcept using vocabulary preferences.

Choose where to run the connection

OMOPHub hosted MCP

Agent connection
Remote Streamable HTTP endpoint
Vocabulary data
OMOPHub API
What you maintain
Client configuration and API key
Best fit
Connect an agent without running a server

Local OMOPHub MCP

Agent connection
Local stdio or your own HTTP process
Vocabulary data
OMOPHub API; requests still leave your network
What you maintain
MCP process, client configuration, and API key
Best fit
A client that needs stdio or a managed local bridge

Your own terminology stack

Agent connection
Your chosen server and agent integration
Vocabulary data
Your chosen terminology backend and data
What you maintain
Vocabulary imports, updates, hosting, and integration
Best fit
Requirements for your own data hosting or server-specific query features

A local MCP process is a bridge to the API, not a local vocabulary database. If you require data to remain within your network or need server-specific features such as SNOMED ECL, evaluate a terminology stack that meets those requirements.

The open-source MCP package also supports HTTP and Docker deployment. Its MIT software licence does not replace vocabulary-content licensing requirements.

Frequently asked questions

Does OMOPHub have a hosted MCP server?

Yes. Connect to https://mcp.omophub.com with your OMOPHub API key. The open-source @omophub/omophub-mcp package also runs locally over stdio or as an HTTP server. Version 1.6.3 exposes 11 terminology tools.

Can I connect OMOPHub MCP to ChatGPT?

ChatGPT desktop can use the Codex configuration on a local Codex host. OMOPHub’s hosted MCP tools require a bearer API key. A direct connection from ChatGPT on the web would require an OAuth-enabled OMOPHub MCP endpoint.

Are SNOMED CT codes, LOINC codes, and OMOP concept IDs the same thing?

No. A source code belongs to a vocabulary such as SNOMED CT or LOINC. An OMOP concept_id identifies its record in the OMOP vocabulary. Use get_concept_by_code with both vocabulary_id and concept_code to retrieve the corresponding OMOP record; use get_concept when you already have its concept_id.

Can I try it for free?

The free plan includes 3,000 API calls per month. MCP tools use the API key’s plan and quotas. A tool may make more than one API request; tool invocations are not a separate unlimited allowance.

Will a connected LLM still make mistakes?

It can. Tools let an agent retrieve and verify codes instead of relying only on model memory, but do not guarantee that it selects the clinically appropriate concept. Check the returned vocabulary, code, display, standard status, and clinical context before using a result.

Should I send patient data to OMOPHub?

No. Send terminology codes, concept IDs, and search terms without patient-linked information. Do not send PHI or patient notes. Running the MCP package locally still sends vocabulary requests to OMOPHub’s remote API.

Does an API key replace SNOMED CT or LOINC licensing requirements?

No. An OMOPHub API key authenticates access; it does not grant or replace third-party vocabulary licences. Your use must comply with the vocabulary owners’ terms and any licensing requirements for your territory and intended use. Review the OMOPHub Terms of Service before integrating.

Which vocabulary release do MCP tools use?

MCP version 1.6.3 uses the API’s default vocabulary release, which can change. Its tools do not expose a vocab_release parameter. For reproducible, release-pinned lookups, use the REST API or an SDK with an explicit vocab_release, as described in the Vocabulary Releases guide.

Put vocabulary lookups into your next agent workflow.

Start with a key and one client configuration. For frameworks without MCP, expose the REST API or an SDK call as a tool in your own application.