HLA-Verify
HLA nomenclature and match checks against a pinned IPD-IMGT/HLA release. No patient identifiers.
Should I use this
Quality & Safety
A
Based on automated analysis of tool definitions and protocol compliance.
Context Cost
~10,913Tokens (tool definitions)
~6.8 KBTypical response size
Significant attention impact (8.53% of 128k context)
This is the approximate number of tokens consumed each time the server's tools are loaded into a model's context. Higher counts reduce the attention available for other tasks.
Install
One-Click Install
Add this to your `claude_desktop_config.json` file:
{
"mcpServers": {
"hla-verify": {
"url": "https://api.hlaverify.com/mcp"
}
}
}Remote endpoints
https://api.hlaverify.com/mcpstreamable-httpWhat it can do
Tool inventory
Tools (15)
🟢 Read-only🟡 Write🔴 Delete⚪ Unknown
🟢verify_text(text)
Scan HLA typing report text, or model output about HLA, for allele-shaped tokens and classify each one: valid / legacy spelling such as A*0201 or Cw*0702 (valid, with modern form and flag deprecated_name) / G-P group / deleted (with successor) / fabricated / NMDP MAC code (seen, not expanded) / KIR name (out of scope, not checked); a valid token with fewer than four fields carries resolution, what that field count does and does not distinguish. Nomenclature checking against a pinned IPD-IMGT/HLA release, not interpretation of a case. Use on any AI-generated or transcribed content mentioning HLA. Send the HLA content only, with patient identifiers removed first.
Input Schema
{
"type": "object",
"properties": {
"text": {
"type": "string",
"maxLength": 200000,
"description": "HLA typing report text, or model output about HLA typing, to scan for allele names. Send the HLA content only: strip patient names, medical record numbers, dates of birth, accession and case identifiers, and any other patient details before sending. The caller is responsible for de-identifying the text; this service neither needs nor wants identifiers and does not store request bodies."
}
},
"required": [
"text"
],
"additionalProperties": false
}Output Schema
{
"type": "object",
"properties": {
"release": {
"type": "string",
"description": "IPD-IMGT/HLA release every verdict was computed against."
},
"clean": {
"type": "boolean",
"description": "The guardrail: true only when no token is hallucinated, fabricated_group or deleted. Gate on this before presenting the text. NMDP multiple allele codes (counts.mac_code) and KIR allele names (counts.out_of_scope) are not checked — treat them as unverified."
},
"counts": {
"type": "object",
"description": "Number of distinct tokens per status.",
"required": [
"valid",
"deleted",
"group",
"fabricated_group",
"hallucinated",
"mac_code",
"out_of_scope"
],
"properties": {
"valid": {
"type": "integer"
},
"deleted": {
"type": "integer"
},
"group": {
"type": "integer"
},
"fabricated_group": {
"type": "integer"
},
"hallucinated": {
"type": "integer"
},
"mac_code": {
"type": "integer",
"description": "NMDP multiple allele codes (A*02:AB) seen but not expanded."
},
"out_of_scope": {
"type": "integer",
"description": "KIR allele names (KIR3DL1*001) seen; a gene family outside IPD-IMGT/HLA, not checked."
}
}
},
"tokens": {
"type": "array",
"description": "Each distinct allele-shaped token found, sorted by token.",
"items": {
"type": "object",
"required": [
"token",
"status",
"note"
],
"properties": {
"token": {
"type": "string",
"description": "The token without any HLA- prefix."
},
"status": {
"type": "string",
"enum": [
"valid",
"group",
"deleted",
"fabricated_group",
"hallucinated",
"mac_code",
"out_of_scope"
],
"description": "valid: assigned (or a valid prefix; A*02:XX and two-field A*02:01g are checked by the name they abbreviate, and a legacy spelling such as A*0201, Cw*0702 or Cw*07:02 by the current name it stands for, with flag deprecated_name); group: a real G/P group; deleted: no longer current (see successor); fabricated_group: G/P-shaped but no such group; hallucinated: never existed in any release; mac_code: an NMDP multiple allele code, reporting shorthand this service does not expand; out_of_scope: a KIR allele name (IPD-KIR), outside IPD-IMGT/HLA and not checked."
},
"note": {
"type": "string",
"description": "Human-readable meaning of status."
},
"successor": {
"type": "string",
"description": "deleted: the name it was renamed to, when known."
},
"current_2field": {
"type": "string",
"description": "valid/deleted tokens that resolve: current 2-field form."
},
"g_group": {
"type": "string",
"description": "G group; NONE or AMBIGUOUS when there is no single group."
},
"flags": {
"type": "array",
"items": {
"type": "string"
}
},
"resolution": {
"type": "object",
"description": "Present on a name with fewer than four fields: what this resolution level does and does not distinguish.",
"required": [
"fields",
"level",
"distinguishes"
],
"properties": {
"fields": {
"type": "integer",
"enum": [
1,
2,
3
],
"description": "Number of colon-separated fields in the name."
},
"level": {
"type": "string",
"enum": [
"allele_group",
"protein",
"coding_sequence"
],
"description": "1 field: allele_group; 2: protein; 3: coding_sequence."
},
"distinguishes": {
"type": "string",
"description": "What finer typing at the next field would add."
}
}
}
}
}
},
"attribution": {
"type": "string",
"description": "Data attribution (IPD-IMGT/HLA, CC-BY-ND)."
}
},
"required": [
"release",
"tokens",
"counts",
"clean"
]
}🟢normalize_allele(name)
Normalize one reported HLA allele name (any era or reporting shorthand: legacy A*0101, Cw*0702 or Cw*07:02, G/P group names, A*02:XX, two-field A*02:01g, optional HLA- prefix) to current 2-field form, with G group, P group, serologic equivalent, and flags. NMDP MAC codes (A*02:AB) are recognised but not expanded (flag mac_code).
Input Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 64,
"description": "One reported HLA allele name, any nomenclature era. An allele string only, never a patient name, medical record number or other identifier."
}
},
"required": [
"name"
],
"additionalProperties": false
}Output Schema
{
"type": "object",
"properties": {
"reported": {
"type": "string",
"description": "The input, verbatim."
},
"current_name": {
"type": "string",
"description": "Current full name in the pinned release, or UNRESOLVABLE."
},
"allele_2field": {
"type": "string",
"description": "Current 2-field form, or UNRESOLVABLE. Never present an UNRESOLVABLE name as an allele."
},
"g_group": {
"type": "string",
"description": "G group; NONE (no group), AMBIGUOUS (members differ) or UNRESOLVABLE."
},
"flags": {
"type": "array",
"items": {
"type": "string"
},
"description": "e.g. deprecated_name, nonexistent_allele, null_allele, g_group_name, p_group_name, xx_code, lg_notation, mac_code."
}
},
"required": [
"reported",
"current_name",
"allele_2field",
"g_group",
"flags"
]
}🟢allele_info(name)
Look up one name in the pinned release and return what it is: assigned (G/P group, first release, confirmed status, WMDA serology, null flag), valid_prefix (member count and sample, plus resolution: what a name with fewer than four fields does and does not distinguish), group (a G or P group name: member count and sample), or deleted (successor). Reported shorthands are accepted as /v1/normalize accepts them — legacy spellings (A*0101, Cw*0702, Cw*07:02), the XX code (A*02:XX), two-field A*02:01g, an optional HLA- prefix — and answer with the facts of the name they stand for plus resolves_to and a flag (deprecated_name, xx_code, lg_notation); an NMDP multiple allele code (A*02:AB) returns mac_code, recognised but not expanded. Not found if the name has never existed in any release.
Input Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 64,
"description": "An HLA allele name of any era: exact name, lower-resolution prefix, deleted name, G/P group, legacy colon-less name, XX code or lg notation. An allele string only, never a patient name, medical record number or other identifier."
}
},
"required": [
"name"
],
"additionalProperties": false
}Output Schema
{
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "Present only when the name is not assigned in this release (and then no other field is)."
},
"release": {
"type": "string",
"description": "IPD-IMGT/HLA release every verdict was computed against."
},
"name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"assigned",
"valid_prefix",
"group",
"deleted",
"mac_code"
],
"description": "assigned: an exact allele in this release; valid_prefix: a lower-resolution prefix of assigned alleles; group: a G or P group name (see group_type); deleted: withdrawn or renamed (see successor); mac_code: an NMDP multiple allele code (A*02:AB), recognised but not expanded or checked."
},
"resolves_to": {
"type": "string",
"description": "Present when the name was a reported shorthand (legacy colon-less or Cw spelling, XX code, lg notation): the current-style name it stands for, whose facts this result carries."
},
"flags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present for a shorthand: deprecated_name (legacy spelling: colon-less A*0101, or the Cw locus label as in Cw*07:02), xx_code, lg_notation, or mac_code. Absent for a plain name."
},
"note": {
"type": "string",
"description": "mac_code: what a multiple allele code is and why it is not expanded."
},
"successor": {
"type": [
"string",
"null"
],
"description": "deleted: the current name, or null if none."
},
"g_group": {
"type": [
"string",
"null"
],
"description": "assigned: G group, or null."
},
"p_group": {
"type": [
"string",
"null"
],
"description": "assigned: P group, or null."
},
"first_release": {
"type": [
"string",
"null"
],
"description": "assigned: first release the exact name appeared in."
},
"confirmed": {
"type": "boolean",
"description": "assigned: confirmed (vs unconfirmed) allele."
},
"serology": {
"type": "object",
"description": "assigned: WMDA serologic equivalents by column (non-empty columns only), as published in rel_dna_ser.txt: an antigen number, '?' (undetermined equivalent) or '∅' (no serological equivalent, null). The lab tools report these as 'uncertain' and 'null'.",
"properties": {
"unambiguous": {
"type": "array",
"items": {
"type": "string"
}
},
"possible": {
"type": "array",
"items": {
"type": "string"
}
},
"assumed": {
"type": "array",
"items": {
"type": "string"
}
},
"expert": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
},
"null_allele": {
"type": "boolean",
"description": "assigned: true for an N (null, not expressed) allele."
},
"ligands": {
"type": "object",
"description": "Class I (A/B/C) ligand facts, aggregated over member alleles: 'ambiguous' when members disagree, 'unknown' when no residue data.",
"required": [
"expressed",
"leader_21",
"residue_80",
"bw",
"c_group",
"kir_ligand"
],
"properties": {
"expressed": {
"type": "boolean",
"description": "false when every member allele is null (not expressed)."
},
"leader_21": {
"type": "string",
"description": "Residue at leader position -21 (M or T; another letter is possible), ambiguous, unknown or not_expressed."
},
"residue_80": {
"type": "string",
"description": "Residue at position 80 (amino-acid letter), ambiguous, unknown or not_expressed."
},
"bw": {
"type": [
"string",
"null"
],
"description": "Bw4 / Bw6 / non-Bw4 / unclassified / ambiguous / unknown / not_expressed; null for HLA-C."
},
"c_group": {
"type": [
"string",
"null"
],
"description": "C1 / C2 / unclassified / ambiguous / unknown; null when not applicable."
},
"kir_ligand": {
"type": "string",
"description": "C1 / C2 / Bw4 / Bw4-80I / Bw4-80T / none / ambiguous / unknown."
},
"ambiguities": {
"type": "object",
"description": "For each ambiguous field, the distinct member values.",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"group_type": {
"type": "string",
"enum": [
"G",
"P"
],
"description": "group: whether the name is a G group (identical exons 2+3 / exon 2) or a P group (identical peptide-binding domain)."
},
"members_count": {
"type": "integer",
"description": "valid_prefix / group: number of assigned alleles under the prefix or in the group."
},
"members_sample": {
"type": "array",
"items": {
"type": "string"
},
"description": "valid_prefix / group: up to 10 member alleles."
},
"resolution": {
"type": "object",
"description": "Present on a name with fewer than four fields: what this resolution level does and does not distinguish.",
"required": [
"fields",
"level",
"distinguishes"
],
"properties": {
"fields": {
"type": "integer",
"enum": [
1,
2,
3
],
"description": "Number of colon-separated fields in the name."
},
"level": {
"type": "string",
"enum": [
"allele_group",
"protein",
"coding_sequence"
],
"description": "1 field: allele_group; 2: protein; 3: coding_sequence."
},
"distinguishes": {
"type": "string",
"description": "What finer typing at the next field would add."
}
}
},
"attribution": {
"type": "string",
"description": "Data attribution (IPD-IMGT/HLA, CC-BY-ND)."
}
},
"description": "Found: release, name, status and the status-specific fields. Never assigned: only `detail`."
}🟢match_score(recipient, donor, framework)
Count a donor-recipient HLA match by the published counting rules (R1-R6): allele arithmetic over chromosomes, not a donor recommendation. recipient/donor: {"A": ["A*01:01","A*02:01"], "B": [...], ...} (two reported alleles per locus, any nomenclature era including G/P group names such as A*02:01:01G; allele strings only, no patient identifiers). framework: 6/6, 8/8, 10/10, 12/12, or antigen. Returns count, per-locus verdicts, GvH/HvG mismatch counts, and flags; unresolvable typing yields 'potential', never a confident count.
Input Schema
{
"type": "object",
"properties": {
"recipient": {
"type": "object",
"description": "locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers.",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
},
"donor": {
"type": "object",
"description": "locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers.",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
},
"framework": {
"type": "string",
"enum": [
"6/6",
"8/8",
"10/10",
"12/12",
"antigen"
],
"default": "8/8"
}
},
"required": [
"recipient",
"donor"
],
"additionalProperties": false
}Output Schema
{
"type": "object",
"properties": {
"release": {
"type": "string",
"description": "IPD-IMGT/HLA release every verdict was computed against."
},
"framework": {
"type": "string",
"enum": [
"6/6",
"8/8",
"10/10",
"12/12",
"antigen"
]
},
"count": {
"type": "string",
"description": "'matched/total' over the resolvable loci only, or UNRESOLVABLE when none resolves. Check verdicts for 'potential' loci before quoting it as a confident count."
},
"verdicts": {
"type": "object",
"description": "Framework locus -> verdict.",
"additionalProperties": {
"type": "string",
"enum": [
"match",
"mismatch",
"potential"
],
"description": "potential: typing missing or not resolvable at the framework's level; excluded from count."
}
},
"hvg_mismatches": {
"type": "integer",
"description": "Host-versus-graft mismatches over non-potential loci."
},
"gvh_mismatches": {
"type": "integer",
"description": "Graft-versus-host mismatches over non-potential loci."
},
"flags": {
"type": "array",
"items": {
"type": "string"
},
"description": "e.g. resolution_insufficient, null_allele, null_allele_mismatch."
},
"attribution": {
"type": "string",
"description": "Data attribution (IPD-IMGT/HLA, CC-BY-ND)."
}
},
"required": [
"release",
"framework",
"count",
"verdicts",
"hvg_mismatches",
"gvh_mismatches",
"flags"
]
}🟢check_typing(typing)
QC-check one HLA typing (all loci) against the pinned release: resolves every reported allele, flags unresolvable/outdated/locus-mismatched/null alleles, flags too-many/single/homozygous per locus, computes the B-leader (-21 M/T) and KIR-ligand (C1/C2/Bw4) profile, and DRB3/4/5 expected-vs-reported. Nomenclature and internal-consistency checking of the report, not clinical interpretation. typing: {"A": ["A*01:01", "A*02:01"], "B": [...], "DRB1": [...], ...} (any nomenclature era, G/P group names, A*02:XX and two-field A*02:01g included; NMDP MAC codes are flagged, not expanded; allele strings only, no patient identifiers).
Input Schema
{
"type": "object",
"properties": {
"typing": {
"type": "object",
"description": "locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers.",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"required": [
"typing"
],
"additionalProperties": false
}Output Schema
{
"type": "object",
"properties": {
"release": {
"type": "string",
"description": "IPD-IMGT/HLA release every verdict was computed against."
},
"valid": {
"type": "boolean",
"description": "true when there are no error-severity issues. Gate on this before using the typing."
},
"loci": {
"type": "object",
"description": "Reported locus key -> one row per reported allele, in input order.",
"additionalProperties": {
"type": "array",
"items": {
"type": "object",
"required": [
"reported",
"status",
"current_name",
"allele_2field",
"g_group",
"flags",
"antigen"
],
"properties": {
"reported": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"ok",
"renamed",
"unresolvable"
]
},
"current_name": {
"type": "string",
"description": "Current name, or UNRESOLVABLE."
},
"allele_2field": {
"type": "string",
"description": "Current 2-field form, or UNRESOLVABLE."
},
"g_group": {
"type": "string",
"description": "G group; NONE, AMBIGUOUS or UNRESOLVABLE."
},
"flags": {
"type": "array",
"items": {
"type": "string"
}
},
"antigen": {
"type": "string",
"description": "WMDA serologic antigen, or 'null' (not expressed) / 'uncertain'."
},
"ligands": {
"type": "object",
"description": "Class I (A/B/C) ligand facts, aggregated over member alleles: 'ambiguous' when members disagree, 'unknown' when no residue data.",
"required": [
"expressed",
"leader_21",
"residue_80",
"bw",
"c_group",
"kir_ligand"
],
"properties": {
"expressed": {
"type": "boolean",
"description": "false when every member allele is null (not expressed)."
},
"leader_21": {
"type": "string",
"description": "Residue at leader position -21 (M or T; another letter is possible), ambiguous, unknown or not_expressed."
},
"residue_80": {
"type": "string",
"description": "Residue at position 80 (amino-acid letter), ambiguous, unknown or not_expressed."
},
"bw": {
"type": [
"string",
"null"
],
"description": "Bw4 / Bw6 / non-Bw4 / unclassified / ambiguous / unknown / not_expressed; null for HLA-C."
},
"c_group": {
"type": [
"string",
"null"
],
"description": "C1 / C2 / unclassified / ambiguous / unknown; null when not applicable."
},
"kir_ligand": {
"type": "string",
"description": "C1 / C2 / Bw4 / Bw4-80I / Bw4-80T / none / ambiguous / unknown."
},
"ambiguities": {
"type": "object",
"description": "For each ambiguous field, the distinct member values.",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
}
}
},
"issues": {
"type": "array",
"items": {
"type": "object",
"required": [
"severity",
"locus",
"code",
"detail"
],
"properties": {
"severity": {
"type": "string",
"enum": [
"error",
"warning",
"info"
],
"description": "Any error makes the typing invalid."
},
"locus": {
"type": "string",
"description": "The locus key as reported."
},
"code": {
"type": "string",
"description": "unresolvable, deprecated_name, locus_mismatch, null_allele, too_many_alleles, single_allele, homozygous, drb345_unexpected or drb345_not_reported."
},
"detail": {
"type": "string"
}
}
}
},
"counts": {
"type": "object",
"required": [
"error",
"warning",
"info"
],
"properties": {
"error": {
"type": "integer"
},
"warning": {
"type": "integer"
},
"info": {
"type": "integer"
}
}
},
"profile": {
"type": "object",
"required": [
"b_leader_genotype",
"c_kir_ligand_genotype",
"kir_ligands_present",
"kir_ligand_status"
],
"properties": {
"b_leader_genotype": {
"type": [
"string",
"null"
],
"description": "HLA-B -21 leader genotype such as M/T ('?' unknown); null when B is not typed."
},
"c_kir_ligand_genotype": {
"type": [
"string",
"null"
],
"description": "HLA-C KIR ligand genotype such as C1/C2 ('none', '?'); null when C is not typed."
},
"kir_ligands_present": {
"type": "array",
"items": {
"type": "string"
},
"description": "Sorted subset of C1, C2, Bw4, Bw4-80I, Bw4-80T."
},
"kir_ligand_status": {
"type": "string",
"enum": [
"complete",
"incomplete"
],
"description": "complete only with two classified alleles at each of A, B and C."
}
}
},
"drb345": {
"type": [
"object",
"null"
],
"description": "DRB3/4/5 expected from DRB1 vs reported; null when DRB1 is not typed.",
"required": [
"expected",
"reported",
"determinate"
],
"properties": {
"expected": {
"type": "array",
"items": {
"type": "string"
}
},
"reported": {
"type": "array",
"items": {
"type": "string"
}
},
"determinate": {
"type": "boolean"
}
}
},
"attribution": {
"type": "string",
"description": "Data attribution (IPD-IMGT/HLA, CC-BY-ND)."
}
},
"required": [
"release",
"valid",
"loci",
"issues",
"counts",
"profile",
"drb345"
]
}🟢donor_compat(recipient, donor)
Donor/recipient immunogenetic compatibility under two published rule sets: HLA-B leader match (-21 M/T, Petersdorf 2020) for a single HLA-B mismatch, and KIR ligand (C1/C2/Bw4) class comparison, computed over each side's full typing QC. Rule checking against published frameworks; it does not rank or recommend a donor. recipient/donor: {"A": [...], "B": [...], "C": [...], "DRB1": [...], ...} (allele strings only, no patient identifiers). Decision support only; not a medical device.
Input Schema
{
"type": "object",
"properties": {
"recipient": {
"type": "object",
"description": "locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers.",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
},
"donor": {
"type": "object",
"description": "locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers.",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"required": [
"recipient",
"donor"
],
"additionalProperties": false
}Output Schema
{
"type": "object",
"properties": {
"release": {
"type": "string",
"description": "IPD-IMGT/HLA release every verdict was computed against."
},
"b_leader": {
"type": "object",
"required": [
"recipient",
"donor",
"b_mismatches",
"leader_match",
"rule"
],
"properties": {
"recipient": {
"type": [
"string",
"null"
],
"description": "Recipient HLA-B leader genotype, e.g. M/T; null when B is not typed."
},
"donor": {
"type": [
"string",
"null"
],
"description": "Donor HLA-B leader genotype; null when B is not typed."
},
"b_mismatches": {
"type": [
"integer",
"null"
],
"description": "HLA-B mismatch count; null when B is missing, over-typed or unresolvable on either side."
},
"leader_match": {
"type": [
"boolean",
"null"
],
"description": "Set only for exactly one HLA-B mismatch with a known M/T leader on both mismatched alleles; otherwise null (not assessable)."
},
"rule": {
"type": "string"
}
}
},
"kir_ligands": {
"type": "object",
"required": [
"recipient",
"donor",
"missing_in_recipient",
"missing_in_donor",
"status",
"rule"
],
"properties": {
"recipient": {
"type": "array",
"items": {
"type": "string"
},
"description": "KIR ligand classes present (C1, C2, Bw4)."
},
"donor": {
"type": "array",
"items": {
"type": "string"
}
},
"missing_in_recipient": {
"type": "array",
"items": {
"type": "string"
}
},
"missing_in_donor": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"complete",
"incomplete"
],
"description": "Treat missing_in_* as provisional unless complete."
},
"rule": {
"type": "string"
}
}
},
"recipient_valid": {
"type": "boolean",
"description": "Recipient typing QC had no errors."
},
"donor_valid": {
"type": "boolean",
"description": "Donor typing QC had no errors."
},
"issues": {
"type": "object",
"required": [
"recipient",
"donor"
],
"properties": {
"recipient": {
"type": "array",
"items": {
"type": "object",
"required": [
"severity",
"locus",
"code",
"detail"
],
"properties": {
"severity": {
"type": "string",
"enum": [
"error",
"warning",
"info"
],
"description": "Any error makes the typing invalid."
},
"locus": {
"type": "string",
"description": "The locus key as reported."
},
"code": {
"type": "string",
"description": "unresolvable, deprecated_name, locus_mismatch, null_allele, too_many_alleles, single_allele, homozygous, drb345_unexpected or drb345_not_reported."
},
"detail": {
"type": "string"
}
}
}
},
"donor": {
"type": "array",
"items": {
"type": "object",
"required": [
"severity",
"locus",
"code",
"detail"
],
"properties": {
"severity": {
"type": "string",
"enum": [
"error",
"warning",
"info"
],
"description": "Any error makes the typing invalid."
},
"locus": {
"type": "string",
"description": "The locus key as reported."
},
"code": {
"type": "string",
"description": "unresolvable, deprecated_name, locus_mismatch, null_allele, too_many_alleles, single_allele, homozygous, drb345_unexpected or drb345_not_reported."
},
"detail": {
"type": "string"
}
}
}
}
}
},
"attribution": {
"type": "string",
"description": "Data attribution (IPD-IMGT/HLA, CC-BY-ND)."
}
},
"required": [
"release",
"b_leader",
"kir_ligands",
"recipient_valid",
"donor_valid",
"issues"
]
}🟢validate_gl_string(gl)
Validate and normalize a GL String (Genotype List, ^ | + ~ / grammar): resolves every allele token, flags outdated/unresolvable names and structural problems (mixed loci within a slash-list, a repeated locus within a haplotype or across ^ blocks, more than two haplotypes, differing loci across a genotype or genotype list, empty elements), and returns the normalized string. Grammar and nomenclature checking only; send allele names, not patient identifiers.
Input Schema
{
"type": "object",
"properties": {
"gl": {
"type": "string",
"maxLength": 100000,
"description": "GL String to validate and normalize. Allele names and GL grammar only, never patient identifiers."
}
},
"required": [
"gl"
],
"additionalProperties": false
}Output Schema
{
"type": "object",
"properties": {
"release": {
"type": "string",
"description": "IPD-IMGT/HLA release every verdict was computed against."
},
"valid": {
"type": "boolean",
"description": "true when there are no error-severity issues."
},
"normalized_gl": {
"type": "string",
"description": "The GL String with outdated names replaced by current ones."
},
"changed": {
"type": "boolean",
"description": "normalized_gl differs from the trimmed input."
},
"loci": {
"type": "array",
"items": {
"type": "string"
}
},
"alleles": {
"type": "array",
"description": "Each distinct allele token, in first-seen order.",
"items": {
"type": "object",
"required": [
"token",
"status",
"current_name",
"locus"
],
"properties": {
"token": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"valid",
"renamed",
"group",
"unresolvable"
]
},
"current_name": {
"type": [
"string",
"null"
],
"description": "null when unresolvable."
},
"locus": {
"type": [
"string",
"null"
]
}
}
}
},
"issues": {
"type": "array",
"items": {
"type": "object",
"required": [
"severity",
"code",
"detail"
],
"properties": {
"severity": {
"type": "string",
"enum": [
"error",
"warning"
]
},
"code": {
"type": "string",
"description": "unresolvable_allele, renamed_allele, whitespace_in_name, empty_element, mixed_locus_allele_list, haplotype_repeats_locus, genotype_loci_differ, more_than_two_haplotypes, genotype_list_loci_differ or locus_repeated_across_blocks."
},
"detail": {
"type": "string"
}
}
}
},
"counts": {
"type": "object",
"required": [
"error",
"warning"
],
"properties": {
"error": {
"type": "integer"
},
"warning": {
"type": "integer"
}
}
},
"attribution": {
"type": "string",
"description": "Data attribution (IPD-IMGT/HLA, CC-BY-ND)."
}
},
"required": [
"release",
"valid",
"normalized_gl",
"changed",
"loci",
"alleles",
"issues",
"counts"
]
}🟢pgx_lookup(typing, alleles)
Which drugs an HLA typing carries a published pharmacogenomic association for. Looks each allele up in hla-pgx-open (CPIC guidelines + PharmGKB clinical annotations, CC BY-SA, snapshot date in every answer) after normalizing the name first, so any era or shorthand works (A*3101, B*5701, HLA-B*15:02:01G) and every conversion leaves a flag. Returns per allele the current name, the two-field form, the flags and the associations (source, drug, evidence level, CPIC testing recommendation, implication, recommendation, guideline or annotation URL, PMIDs), plus summary.actionable: the CPIC level-A, allele-positive rows. Guideline lookup over published CPIC and PharmGKB associations, keyed by two-field HLA allele. Decision support only; not a medical device. After an allogeneic transplant the recipient's blood carries the donor's genome, and which genome should drive an HLA-mediated drug alert is an open question (NCT06856226); this lookup reports both and decides nothing. Allele strings only, no patient identifiers.
Input Schema
{
"type": "object",
"properties": {
"typing": {
"type": "object",
"description": "locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers.",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
},
"alleles": {
"type": "array",
"maxItems": 96,
"items": {
"type": "string",
"maxLength": 64
},
"description": "A flat list of reported allele names instead of a typing. Send exactly one of typing or alleles."
}
},
"additionalProperties": false
}Output Schema
{
"type": "object",
"properties": {
"release": {
"type": "string"
},
"pgx_snapshot": {
"type": "object",
"properties": {
"date": {
"type": [
"string",
"null"
]
},
"commit": {
"type": [
"string",
"null"
]
}
},
"description": "The hla-pgx-open snapshot the answer came from (UTC date and git commit)."
},
"scope": {
"type": "string"
},
"license": {
"type": "string"
},
"attribution": {
"type": "string"
},
"alleles": {
"type": "array",
"items": {
"type": "object",
"required": [
"reported",
"current_name",
"allele_2field",
"flags",
"associations"
],
"properties": {
"reported": {
"type": "string"
},
"current_name": {
"type": "string"
},
"allele_2field": {
"type": "string"
},
"flags": {
"type": "array",
"items": {
"type": "string"
}
},
"associations": {
"type": "array",
"items": {
"type": "object",
"description": "One published association for the allele, as hla-pgx-open records it (CPIC or PharmGKB).",
"properties": {
"source": {
"type": "string",
"enum": [
"cpic",
"pharmgkb"
]
},
"source_record_id": {
"type": "string"
},
"gene": {
"type": "string"
},
"allele": {
"type": "string"
},
"allele_status": {
"type": "string",
"description": "positive / negative / carrier, or empty when the source's label is not a status."
},
"source_allele_label": {
"type": "string"
},
"drug": {
"type": "string"
},
"drug_id": {
"type": "string"
},
"evidence_level": {
"type": "string"
},
"clinpgx_level": {
"type": "string"
},
"pgx_testing": {
"type": "string"
},
"phenotype_category": {
"type": "string"
},
"implication": {
"type": "string"
},
"recommendation": {
"type": "string"
},
"classification": {
"type": "string"
},
"population": {
"type": "string"
},
"score": {
"type": "string"
},
"guideline_name": {
"type": "string"
},
"guideline_url": {
"type": "string"
},
"annotation_url": {
"type": "string"
},
"citations_pmid": {
"type": "string"
}
}
}
}
}
}
},
"summary": {
"type": "object",
"properties": {
"names": {
"type": "integer"
},
"unresolvable": {
"type": "integer"
},
"with_associations": {
"type": "integer"
},
"actionable": {
"type": "array",
"items": {
"type": "object",
"description": "One published association for the allele, as hla-pgx-open records it (CPIC or PharmGKB).",
"properties": {
"source": {
"type": "string",
"enum": [
"cpic",
"pharmgkb"
]
},
"source_record_id": {
"type": "string"
},
"gene": {
"type": "string"
},
"allele": {
"type": "string"
},
"allele_status": {
"type": "string",
"description": "positive / negative / carrier, or empty when the source's label is not a status."
},
"source_allele_label": {
"type": "string"
},
"drug": {
"type": "string"
},
"drug_id": {
"type": "string"
},
"evidence_level": {
"type": "string"
},
"clinpgx_level": {
"type": "string"
},
"pgx_testing": {
"type": "string"
},
"phenotype_category": {
"type": "string"
},
"implication": {
"type": "string"
},
"recommendation": {
"type": "string"
},
"classification": {
"type": "string"
},
"population": {
"type": "string"
},
"score": {
"type": "string"
},
"guideline_name": {
"type": "string"
},
"guideline_url": {
"type": "string"
},
"annotation_url": {
"type": "string"
},
"citations_pmid": {
"type": "string"
}
}
},
"description": "CPIC level-A, allele-positive rows: the ones a prescriber acts on."
},
"drugs_actionable": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"required": [
"release",
"pgx_snapshot",
"scope",
"alleles",
"summary"
]
}🟢pgx_pair(recipient, donor)
For a donor-recipient pair, which genome carries each actionable HLA-drug association. Screens both typings as pgx_lookup does and marks every CPIC level-A, allele-positive association in_recipient, in_donor, discordant (present in exactly one) and whose_hla (both / recipient_only / donor_only). Guideline lookup over published CPIC and PharmGKB associations, keyed by two-field HLA allele. Decision support only; not a medical device. After an allogeneic transplant the recipient's blood carries the donor's genome, and which genome should drive an HLA-mediated drug alert is an open question (NCT06856226); this lookup reports both and decides nothing. Allele strings only, no patient identifiers.
Input Schema
{
"type": "object",
"properties": {
"recipient": {
"type": "object",
"description": "Recipient typing: {\"typing\": {...}} or {\"alleles\": [...]}.",
"properties": {
"typing": {
"type": "object",
"description": "locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers.",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
},
"alleles": {
"type": "array",
"maxItems": 96,
"items": {
"type": "string",
"maxLength": 64
}
}
},
"additionalProperties": false
},
"donor": {
"type": "object",
"description": "Donor typing: {\"typing\": {...}} or {\"alleles\": [...]}.",
"properties": {
"typing": {
"type": "object",
"description": "locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers.",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
},
"alleles": {
"type": "array",
"maxItems": 96,
"items": {
"type": "string",
"maxLength": 64
}
}
},
"additionalProperties": false
}
},
"required": [
"recipient",
"donor"
],
"additionalProperties": false
}Output Schema
{
"type": "object",
"properties": {
"release": {
"type": "string"
},
"pgx_snapshot": {
"type": "object",
"properties": {
"date": {
"type": [
"string",
"null"
]
},
"commit": {
"type": [
"string",
"null"
]
}
},
"description": "The hla-pgx-open snapshot the answer came from (UTC date and git commit)."
},
"scope": {
"type": "string"
},
"license": {
"type": "string"
},
"attribution": {
"type": "string"
},
"recipient": {
"type": "object",
"properties": {
"alleles": {
"type": "array",
"items": {
"type": "object",
"required": [
"reported",
"current_name",
"allele_2field",
"flags",
"associations"
],
"properties": {
"reported": {
"type": "string"
},
"current_name": {
"type": "string"
},
"allele_2field": {
"type": "string"
},
"flags": {
"type": "array",
"items": {
"type": "string"
}
},
"associations": {
"type": "array",
"items": {
"type": "object",
"description": "One published association for the allele, as hla-pgx-open records it (CPIC or PharmGKB).",
"properties": {
"source": {
"type": "string",
"enum": [
"cpic",
"pharmgkb"
]
},
"source_record_id": {
"type": "string"
},
"gene": {
"type": "string"
},
"allele": {
"type": "string"
},
"allele_status": {
"type": "string",
"description": "positive / negative / carrier, or empty when the source's label is not a status."
},
"source_allele_label": {
"type": "string"
},
"drug": {
"type": "string"
},
"drug_id": {
"type": "string"
},
"evidence_level": {
"type": "string"
},
"clinpgx_level": {
"type": "string"
},
"pgx_testing": {
"type": "string"
},
"phenotype_category": {
"type": "string"
},
"implication": {
"type": "string"
},
"recommendation": {
"type": "string"
},
"classification": {
"type": "string"
},
"population": {
"type": "string"
},
"score": {
"type": "string"
},
"guideline_name": {
"type": "string"
},
"guideline_url": {
"type": "string"
},
"annotation_url": {
"type": "string"
},
"citations_pmid": {
"type": "string"
}
}
}
}
}
}
},
"unresolvable": {
"type": "integer"
}
}
},
"donor": {
"type": "object",
"properties": {
"alleles": {
"type": "array",
"items": {
"type": "object",
"required": [
"reported",
"current_name",
"allele_2field",
"flags",
"associations"
],
"properties": {
"reported": {
"type": "string"
},
"current_name": {
"type": "string"
},
"allele_2field": {
"type": "string"
},
"flags": {
"type": "array",
"items": {
"type": "string"
}
},
"associations": {
"type": "array",
"items": {
"type": "object",
"description": "One published association for the allele, as hla-pgx-open records it (CPIC or PharmGKB).",
"properties": {
"source": {
"type": "string",
"enum": [
"cpic",
"pharmgkb"
]
},
"source_record_id": {
"type": "string"
},
"gene": {
"type": "string"
},
"allele": {
"type": "string"
},
"allele_status": {
"type": "string",
"description": "positive / negative / carrier, or empty when the source's label is not a status."
},
"source_allele_label": {
"type": "string"
},
"drug": {
"type": "string"
},
"drug_id": {
"type": "string"
},
"evidence_level": {
"type": "string"
},
"clinpgx_level": {
"type": "string"
},
"pgx_testing": {
"type": "string"
},
"phenotype_category": {
"type": "string"
},
"implication": {
"type": "string"
},
"recommendation": {
"type": "string"
},
"classification": {
"type": "string"
},
"population": {
"type": "string"
},
"score": {
"type": "string"
},
"guideline_name": {
"type": "string"
},
"guideline_url": {
"type": "string"
},
"annotation_url": {
"type": "string"
},
"citations_pmid": {
"type": "string"
}
}
}
}
}
}
},
"unresolvable": {
"type": "integer"
}
}
},
"actionable": {
"type": "array",
"items": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"cpic",
"pharmgkb"
]
},
"source_record_id": {
"type": "string"
},
"gene": {
"type": "string"
},
"allele": {
"type": "string"
},
"allele_status": {
"type": "string",
"description": "positive / negative / carrier, or empty when the source's label is not a status."
},
"source_allele_label": {
"type": "string"
},
"drug": {
"type": "string"
},
"drug_id": {
"type": "string"
},
"evidence_level": {
"type": "string"
},
"clinpgx_level": {
"type": "string"
},
"pgx_testing": {
"type": "string"
},
"phenotype_category": {
"type": "string"
},
"implication": {
"type": "string"
},
"recommendation": {
"type": "string"
},
"classification": {
"type": "string"
},
"population": {
"type": "string"
},
"score": {
"type": "string"
},
"guideline_name": {
"type": "string"
},
"guideline_url": {
"type": "string"
},
"annotation_url": {
"type": "string"
},
"citations_pmid": {
"type": "string"
},
"in_recipient": {
"type": "boolean"
},
"in_donor": {
"type": "boolean"
},
"discordant": {
"type": "boolean"
},
"whose_hla": {
"type": "string",
"enum": [
"both",
"recipient_only",
"donor_only",
"neither"
]
}
}
}
},
"summary": {
"type": "object",
"properties": {
"actionable": {
"type": "integer"
},
"discordant": {
"type": "integer"
},
"drugs": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"required": [
"release",
"pgx_snapshot",
"scope",
"recipient",
"donor",
"actionable",
"summary"
]
}🟢translate_names(names, from, to)
Translate HLA allele names from one IPD-IMGT/HLA release to another, through each allele's HLA ID, using the official Allelelist_history.txt (every release since 1.05.0). Give the names as they were written in release `from` (omit `from` to accept a name used in any release); `to` defaults to the current release. Each row says unchanged, renamed (to_name), deleted (reason, successor and its name in `to`), not_yet_named, not_in_from_release, ambiguous (each allele listed) or unknown. Use it when data typed under an older release has to be compared with or reported under a newer one. Lab shorthand (B*1501, A*02:XX) belongs in normalize_allele first. Allele strings only, no patient identifiers.
Input Schema
{
"type": "object",
"properties": {
"names": {
"type": "array",
"minItems": 1,
"maxItems": 5000,
"items": {
"type": "string",
"maxLength": 64
},
"description": "Allele names exactly as written in the `from` release."
},
"from": {
"type": "string",
"maxLength": 16,
"description": "An IPD-IMGT/HLA release, like \"3.40.0\" (1.05.0 to the current one)."
},
"to": {
"type": "string",
"maxLength": 16,
"description": "An IPD-IMGT/HLA release, like \"3.40.0\" (1.05.0 to the current one)."
}
},
"required": [
"names"
],
"additionalProperties": false
}Output Schema
{
"type": "object"
}🟢release_diff(from, to, locus, limit)
Which HLA allele names were added, removed (with the deletion reason and successor) and renamed between two IPD-IMGT/HLA releases, optionally for one locus. Counts are complete; each list is cut at `limit` and `truncated` says so. Use it to see what a release update changes before re-running or re-reporting typings.
Input Schema
{
"type": "object",
"properties": {
"from": {
"type": "string",
"maxLength": 16,
"description": "An IPD-IMGT/HLA release, like \"3.40.0\" (1.05.0 to the current one)."
},
"to": {
"type": "string",
"maxLength": 16,
"description": "An IPD-IMGT/HLA release, like \"3.40.0\" (1.05.0 to the current one)."
},
"locus": {
"type": "string",
"maxLength": 8,
"description": "One locus, like \"A\" or \"DRB1\"."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 5000,
"description": "Maximum items per list (default 500)."
}
},
"required": [
"from",
"to"
],
"additionalProperties": false
}Output Schema
{
"type": "object"
}🟢allele_history(name, as_of)
Every name the allele behind an HLA name has had, release by release since IPD-IMGT/HLA 1.05.0: its HLA ID, current name, the first and last release that used this name, the full timeline of names, and the deletion note if the name was retired. `as_of` adds what it was called in that release. Use it to answer when a name appeared, changed or disappeared. An allele string only, no patient identifiers.
Input Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 64,
"description": "An allele name as written in any release, like \"A*0101\"."
},
"as_of": {
"type": "string",
"maxLength": 16,
"description": "An IPD-IMGT/HLA release, like \"3.40.0\" (1.05.0 to the current one)."
}
},
"required": [
"name"
],
"additionalProperties": false
}Output Schema
{
"type": "object"
}🟡beta_signup(email, org, use_case, source)
Put a user on the free public beta's notification list for paid API keys. Ask before calling: it records the address they give you. Re-signing the same address is safe (status already_recorded). Someone who needs a higher rate limit today should email [email protected] for a beta key instead of waiting.
Input Schema
{
"type": "object",
"properties": {
"email": {
"type": "string",
"maxLength": 254,
"description": "The user's email address."
},
"org": {
"type": "string",
"maxLength": 120,
"description": "Lab, company or institution (optional)."
},
"use_case": {
"type": "string",
"maxLength": 500,
"description": "What they would use the API for (optional). No patient details."
},
"source": {
"type": "string",
"maxLength": 120,
"description": "Where the signup came from, e.g. mcp (optional)."
}
},
"required": [
"email"
],
"additionalProperties": false
}Output Schema
{
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"description": "Always true; a rejected signup comes back as an error result."
},
"status": {
"type": "string",
"enum": [
"recorded",
"already_recorded"
],
"description": "already_recorded: the address was already on the list. Both are success — do not retry."
},
"message": {
"type": "string",
"description": "What to tell the user, including how to get a beta key today."
},
"release": {
"type": "string",
"description": "IPD-IMGT/HLA release every verdict was computed against."
}
},
"required": [
"ok",
"status",
"message",
"release"
]
}⚪research_access(email, institution, use_case, expected_volume, source)
Apply for free HLA-Verify access for an academic or nonprofit lab. Ask before calling: it records the address, institution and use case you give it. Approval is manual: a person reads every application, so it is not instant and not guaranteed. If it is approved the applicant is emailed a single-use code that takes 100% off a subscription for 12 months at self-serve checkout, with no card and no contract. Re-applying with the same address is safe (status already_recorded) and never overwrites an application that has already been decided. Commercial labs should buy a tier at https://api.hlaverify.com/pricing instead.
Input Schema
{
"type": "object",
"properties": {
"email": {
"type": "string",
"maxLength": 254,
"description": "The applicant's email address. The approval code is sent here."
},
"institution": {
"type": "string",
"maxLength": 200,
"description": "University, hospital, institute or nonprofit the work is done at."
},
"use_case": {
"type": "string",
"maxLength": 1000,
"description": "What the research or teaching is, and what the API would be used for. This is what the decision is made on, so be specific. No patient details."
},
"expected_volume": {
"type": "string",
"maxLength": 120,
"description": "Rough call or typing volume, e.g. 'about 20,000 typings a month' (optional)."
},
"source": {
"type": "string",
"maxLength": 120,
"description": "Where the application came from, e.g. mcp (optional)."
}
},
"required": [
"email",
"institution",
"use_case"
],
"additionalProperties": false
}Output Schema
{
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"description": "Always true; a rejected application comes back as an error result."
},
"status": {
"type": "string",
"enum": [
"recorded",
"already_recorded"
],
"description": "already_recorded: this address already has an application on file. Both are success; do not retry."
},
"message": {
"type": "string",
"description": "What to tell the user, including that approval is by hand and not instant."
},
"release": {
"type": "string",
"description": "IPD-IMGT/HLA release every verdict was computed against."
}
},
"required": [
"ok",
"status",
"message",
"release"
]
}🟢about
What this server is and is not, what to send it, benchmark evidence for why to use it, the beta state, and terms.
Input Schema
{
"type": "object",
"properties": {},
"additionalProperties": false
}Output Schema
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"release": {
"type": "string",
"description": "IPD-IMGT/HLA release every verdict was computed against."
},
"scope": {
"type": "string"
},
"inputs": {
"type": "string"
},
"why": {
"type": "string"
},
"code": {
"type": "string"
},
"api": {
"type": "string"
},
"demo": {
"type": "string"
},
"agents": {
"type": "string"
},
"limits": {
"type": "string"
},
"commercial": {
"type": "string"
},
"disclaimer": {
"type": "string"
},
"beta": {
"type": "string"
},
"beta_key": {
"type": "string"
},
"beta_signup": {
"type": "string"
},
"research": {
"type": "string"
}
},
"required": [
"name",
"release"
]
}Community
Evidence
Recent observations
verifiedversion not recorded15 tools
verifiedversion not recorded15 tools
verifiedversion not recorded10 tools
verifiedversion not recorded10 tools
verifiedversion not recorded10 tools
verifiedversion not recorded10 tools