Skip to main content
Glama
jesse-smith

searchloinc

by jesse-smith

SearchLOINC

A thin MCP server wrapping the LOINC Search API so LLMs can search LOINC the same way a human does via loinc.org/search — free-text, relevance-ranked, faceted. It targets the documented Search API (https://loinc.regenstrief.org/searchapi/), not the FHIR terminology service.

Setup

uv sync --extra dev
cp .env.example .env   # then fill in your LOINC credentials

Credentials come from a free registration on loinc.org. Set LOINC_USERNAME and LOINC_PASSWORD in the environment (never commit them).

Related MCP server: OMOPHub MCP Server

Run

From a checkout (development):

uv run python -m searchloinc

Or install it as a standalone command and run it from anywhere:

uv tool install .          # puts a `searchloinc` executable on PATH
searchloinc                # starts the stdio server

Both run the server over stdio (the transport MCP clients expect). Point your client at the command, or add it to your client's MCP server config. When you use the installed command, supply credentials through the client's env block (sourced from your secret store / shell — never committed):

{
  "mcpServers": {
    "searchloinc": {
      "command": "searchloinc",
      "env": {
        "LOINC_USERNAME": "your-loinc-username",
        "LOINC_PASSWORD": "your-loinc-password"
      }
    }
  }
}

The checked-in .mcp.json uses the dev form (uv run --env-file .env) so a local checkout picks up credentials from .env automatically.

Tools

Two-tier design — cheap compact search for triage, explicit drill-in for detail:

  • search_loincs — LOINC terms (lab tests, vitals, measurements, panels, surveys). The main table.

  • search_answerlists — enumerated answer sets attached to survey/nominal terms.

  • search_parts — the LP-coded building blocks (components, systems, methods, properties).

  • search_groups — curated collections of related terms.

  • get_loinc(code) — drill into one term by exact code; returns the full flat record.

Each search tool takes query (required), rows, offset, sortorder, language, and include_facets. Pick the scope that matches what you're after; results are relevance-ranked, so if the top hits miss, reformulate rather than deep-page. Triage with a search tool, then get_loinc the code you want.

Output shape

Search responses are a JSON envelope plus a result table:

  • The table is serialized as TOON — a compact tabular format that pays the column-name cost once, so wide uniform tables stay small. Columns are fixed per scope; empty fields render as "" to preserve row uniformity. Tab-delimited (LOINC display values contain commas but never tabs).

  • The envelope reports requested, returned, total, offset, and truncated.

Character budget & pagination. The whole serialized payload is capped at 9500 characters (a cushion under the ~10K downstream tool-result limit). The row-packing loop encodes and measures the full payload incrementally and stops before the cap; when results don't all fit, truncated is true — page forward with offset. include_facets (filter counts) is off by default and opt-in; facet payloads still respect the budget.

get_loinc returns a single JSON object — the flat search-API record with null/empty fields dropped (always keeping Link), so the field set adapts to the term type. Page-only content (part LP hierarchy, language variants, curated part descriptions) is not in the flat record — follow Link to loinc.org for it.

There is a debug-only raw-JSON path toggled by the SEARCHLOINC_RAW_JSON env var; it is never exposed as an agent-facing tool parameter.

Development

uv run ruff check searchloinc   # lint
uv run pytest                   # tests (no network; API stubbed with fixtures)

The /loinc-search skill drives the live API to validate wrapper output against ground truth.

Status

Wrapper is implemented and validated against the live API. Eventual deployment target is a Databricks app (credentials via secret scope, inference via AI Gateway).

License & attribution

The SearchLOINC code is licensed under the MIT License.

This project wraps the LOINC Search API and includes sample LOINC API responses as test fixtures. That LOINC (and referenced SNOMED CT) content is not covered by the MIT license and remains under its own terms — see NOTICE for the required attributions.

This material contains content from LOINC (http://loinc.org). LOINC is copyright © Regenstrief Institute, Inc. and the Logical Observation Identifiers Names and Codes (LOINC) Committee and is available at no cost under the license at http://loinc.org/license. LOINC® is a registered United States trademark of Regenstrief Institute, Inc.

Available Tools

5 tools
get_loincA

Drill into one LOINC term by its exact code (e.g. '783-1') and return the full flat record — all populated fields (names, the six-axis parts, related names, ranks, example units, status/change history) plus Link to loinc.org. This is tier-2 of the search→detail workflow: triage with search_loincs, then get_loinc the code you want. Null/empty fields are dropped, so the field set adapts to the term type. Content that lives only on the loinc.org page (part LP hierarchy, language variants, curated part descriptions) is not in this record — follow Link for it.

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses that null/empty fields are dropped, lists the types of fields returned, and specifies what content is not included (part hierarchy, language variants). Lacks only explicit mention of authorization or rate limits, but these are less critical for a read-only detail lookup.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no redundancy. The main action is front-loaded, and every sentence provides essential information: what it does, workflow context, and caveats about missing data.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given only one parameter, no output schema, and no enums, the description fully covers the needed context: what the tool returns, what it does not, and the workflow in relation to sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description compensates by explaining the single parameter 'code' as an exact code like '783-1', clarifying the input format beyond the schema's plain string type.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Drill into' and the resource 'one LOINC term by its exact code', distinguishing it from sibling search tools by explicitly positioning it as tier-2 of the search→detail workflow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells when to use the tool: after triaging with search_loincs, then get the code. It also describes what is not in this record and to follow the Link for additional content, guiding the agent on limitations and next steps.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_answerlistsA

Search LOINC answer lists (the enumerated answer sets attached to survey/nominal terms, e.g. smoking-status choices). Use when you need the allowed answers for a term rather than the term itself. Results are relevance-ranked by the LOINC Search API (same ranking as the loinc.org/search UI); if the top hits miss, reformulate the query rather than deep-paging. Rows are compact for triage — call get_loinc(code) to drill into the full record for a specific LOINC. Output is a TOON table capped to a character budget; when truncated, page with offset.

ParametersJSON Schema
NameRequiredDescriptionDefault
rowsNo
queryYes
offsetNo
languageNo
sortorderNo
include_facetsNo

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Discloses relevance ranking (same as loinc.org/search UI), truncation behavior with character budget, and recommendation to call get_loinc for full records. Lacks explicit read-only statement but appropriate for a search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single coherent paragraph, front-loaded with purpose. Sentences are efficient, but could benefit from minor restructuring to separate behavior from parameter guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers key aspects: what is searched, ranking, truncation, pagination, and linkage to get_loinc. Missing parameter descriptions but otherwise complete for a search tool with no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but description only explains `offset` in context of pagination. Other parameters (rows, query, language, sortorder, include_facets) are not described, leaving the agent without guidance on their meaning or valid values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Explicitly states 'Search LOINC answer lists' with examples (e.g., smoking-status choices). Distinguishes from siblings by stating 'Use when you need the allowed answers for a term rather than the term itself.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear when-to-use vs alternatives, advises reformulating query instead of deep-paging when top hits miss, and explains pagination with `offset` for truncated results.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_groupsA

Search LOINC groups (curated collections of related terms — e.g. all glucose measurements, or a molecular-conversion group). Use when you want a pre-grouped set of related LOINCs rather than individual terms. Results are relevance-ranked by the LOINC Search API (same ranking as the loinc.org/search UI); if the top hits miss, reformulate the query rather than deep-paging. Rows are compact for triage — call get_loinc(code) to drill into the full record for a specific LOINC. Output is a TOON table capped to a character budget; when truncated, page with offset.

ParametersJSON Schema
NameRequiredDescriptionDefault
rowsNo
queryYes
offsetNo
languageNo
sortorderNo
include_facetsNo

TDQS

A3.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Given no annotations, the description must carry full burden. It discloses that results are relevance-ranked by the LOINC Search API (same as loinc.org/search UI), that rows are compact for triage, that output is a TOON table capped to a character budget, and that pagination uses 'offset'. This is substantial behavioral context, though it could mention sorting behavior or what facets are for.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is fairly concise and front-loaded with purpose. It wastes no words and is structured logically: definition, usage, behavior, pagination. A slight improvement could be combining the rank and page sentences, but overall effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the description covers purpose and broad behavior, it lacks explanations for most parameters (6 total, 0% schema coverage, no parameter descriptions in description). There is no output schema, so return format is only vaguely described as 'TOON table capped to character budget'. For a tool with this complexity, the description leaves significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 6 parameters with 0% description coverage. The description does not explain any parameter beyond implicit mention of 'query' and 'offset' for pagination. 'rows', 'language', 'sortorder', and 'include_facets' are not explained at all, leaving the agent to guess their semantics from titles alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches LOINC groups, defines what they are (curated collections of related terms), and contrasts with searching individual terms. The verb 'search' plus resource 'groups' is specific, and the examples ('all glucose measurements') make it concrete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use when you want a pre-grouped set of related LOINCs rather than individual terms.' It also provides guidance on reformulating queries if top hits miss, avoiding deep-paging, and suggests calling get_loinc for full records. While it doesn't explicitly state when not to use, the guidance is clear and actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_loincsA

Search LOINC terms (observations/measurements — the main LOINC table). Use this for lab tests, vital signs, clinical measurements, panels, and surveys — anything you'd look up by a test name like 'hemoglobin', 'sodium serum', or a LOINC number. Results are relevance-ranked by the LOINC Search API (same ranking as the loinc.org/search UI); if the top hits miss, reformulate the query rather than deep-paging. Rows are compact for triage — call get_loinc(code) to drill into the full record for a specific LOINC. Output is a TOON table capped to a character budget; when truncated, page with offset.

ParametersJSON Schema
NameRequiredDescriptionDefault
rowsNo
queryYes
offsetNo
languageNo
sortorderNo
include_facetsNo

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses relevance ranking, compact rows for triage, character-budget capped output, and pagination with offset. No annotations provided, so description carries full burden. Could mention read-only nature but otherwise transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Efficiently written with front-loaded purpose, then usage tips, ranking behavior, and pagination. No superfluous sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Provides good context for using the tool, including output format (TOON table) and when to use sibling tool. However, missing parameter descriptions and output schema details, leaving some gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Parameter schema coverage is 0%, but description only explains query and offset implicitly. Missing explanations for rows, language, sortorder, and include_facets, which are crucial for proper usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states this tool searches LOINC terms, listing specific examples like lab tests, vital signs, and measurements. It distinguishes from siblings by mentioning get_loinc for drill-down and other search tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance on when to use this tool (for any LOINC search by name or number), and when to reformulate queries instead of deep-paging. Also instructs to use get_loinc for full record details.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_partsA

Search LOINC parts (the LP-coded building blocks — components, systems, methods, properties — that compose LOINC terms). Use when you need the canonical part behind a concept, or to explore the axis vocabulary. Results are relevance-ranked by the LOINC Search API (same ranking as the loinc.org/search UI); if the top hits miss, reformulate the query rather than deep-paging. Rows are compact for triage — call get_loinc(code) to drill into the full record for a specific LOINC. Output is a TOON table capped to a character budget; when truncated, page with offset.

ParametersJSON Schema
NameRequiredDescriptionDefault
rowsNo
queryYes
offsetNo
languageNo
sortorderNo
include_facetsNo

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description carries full burden. Mentions results are relevance-ranked, rows are compact for triage, output is a TOON table capped to character budget, and to page with offset when truncated. Does not mention auth or rate limits, but reasonable for a read operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is two sentences, front-loaded with purpose. Efficiently communicates key behavioral points and usage guidance. Could be slightly more concise, but no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, so description should explain return format. Mentions TOON table capped to character budget but not fields. Does not cover error conditions or language/sortorder/facets. For 6-param tool with no output schema, some gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so description must explain parameters. It explains query, rows, offset (via pagination mention), but fails to describe language, sortorder, and include_facets. Lacks clarity on these three parameters, which could confuse usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool searches LOINC parts and defines them as LP-coded building blocks. It distinguishes from sibling tool get_loinc by noting it returns compact results for triage and to drill into full record with get_loinc. The verb 'search' and resource 'LOINC parts' are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'when you need the canonical part behind a concept, or to explore the axis vocabulary.' Provides guidance on result ranking, suggests reformulating query rather than deep-paging if top hits miss, and recommends calling get_loinc for full details. Differentiates from siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 5 tool updatesv0.1.0
    • First observedget_loinc
    • First observedsearch_answerlists
    • First observedsearch_groups
    • First observedsearch_loincs
    • First observedsearch_parts

TDQS

A4.2/5.0
Disambiguation5/5

Each tool targets a distinct entity (LOINC term, answer list, group, part) or action (search vs. detail). Descriptions clearly differentiate between them, leaving no ambiguity about which tool to use for a given task.

Naming Consistency5/5

Tool names follow a consistent verb_noun pattern: 'search_' for searching different entities and 'get_loinc' for fetching details. All names use lowercase and underscores, maintaining a uniform style.

Tool Count5/5

Five tools cover the core functionalities of searching and retrieving LOINC-related data without being excessive. The count is well-scoped for a focused LOINC search server.

Completeness4/5

The set covers searching for terms, answer lists, groups, and parts, plus detailed term retrieval. However, there is no dedicated detail tool for answer lists or groups; the workflow directs to get_loinc, which may not fully address those entities. This minor gap prevents a perfect score.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    C
    quality
    D
    maintenance
    Allows AI assistants to search the Library of Congress Subject Headings (LCSH) through a simple API interface, making it easy to query and retrieve official subject headings and related terms.
    1
    3
    MIT
  • A
    license
    A
    quality
    A
    maintenance
    Provides AI agents with instant access to 10M+ OMOP medical vocabulary concepts for searching, mapping, and navigating clinical codes across SNOMED, ICD-10, RxNorm, LOINC, and more.
    11
    116
    6
    MIT
  • A
    license
    A
    quality
    D
    maintenance
    Enables LLMs to search FDA drug labels and adverse event data via the OpenFDA API, supporting natural language queries for drug safety information.
    2
    MIT
  • A
    license
    A
    quality
    D
    maintenance
    Enables searching LOINC codes and retrieving detailed information including panel members and answer options via the LOINC Search API.
    2
    1
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jesse-smith/searchloinc'

If you have feedback or need assistance with the MCP directory API, please join our Discord server