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.
claude mcp add omophub --transport http \ --header "Authorization: Bearer oh_your_key_here" \ https://mcp.omophub.com
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.
[mcp_servers.omophub] url = "https://mcp.omophub.com" bearer_token_env_var = "OMOPHUB_API_KEY"
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.
{
"mcpServers": {
"omophub": {
"url": "https://mcp.omophub.com",
"headers": {
"Authorization": "Bearer oh_your_key_here"
}
}
}
}VS Code
.vscode/mcp.json
Set OMOPHUB_API_KEY in the environment that starts VS Code. Run MCP: List Servers and start omophub.
{
"servers": {
"omophub": {
"type": "http",
"url": "https://mcp.omophub.com",
"headers": {
"Authorization": "Bearer ${env:OMOPHUB_API_KEY}"
}
}
}
}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.
{
"mcpServers": {
"omophub": {
"command": "npx",
"args": [
"-y",
"@omophub/omophub-mcp@1.6.3"
],
"env": {
"OMOPHUB_API_KEY": "oh_your_key_here"
}
}
}
}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 sourceUse 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.