HLA nomenclature and match checks against a pinned IPD-IMGT/HLA release. No patient identifiers.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Optional. Without a key /mcp shares the free tier (60 requests/minute); keys: https://api.hlaverify.com/pricing
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
What this server is and is not, what to send it, benchmark evidence for why to use it, the beta state, and terms.
This tool takes no arguments.
What this server is and is not, what to send it, benchmark evidence for why to use it, the beta state, and terms.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| name* | string | An allele name as written in any release, like "A*0101". |
| as_of | string | An IPD-IMGT/HLA release, like "3.40.0" (1.05.0 to the current one). |
{
"type": "object",
"required": [
"name"
],
"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)."
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| name* | string | 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. |
{
"type": "object",
"required": [
"name"
],
"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."
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| org | string | Lab, company or institution (optional). |
| email* | string | The user's email address. |
| source | string | Where the signup came from, e.g. mcp (optional). |
| use_case | string | What they would use the API for (optional). No patient details. |
{
"type": "object",
"required": [
"email"
],
"properties": {
"org": {
"type": "string",
"maxLength": 120,
"description": "Lab, company or institution (optional)."
},
"email": {
"type": "string",
"maxLength": 254,
"description": "The user's email address."
},
"source": {
"type": "string",
"maxLength": 120,
"description": "Where the signup came from, e.g. mcp (optional)."
},
"use_case": {
"type": "string",
"maxLength": 500,
"description": "What they would use the API for (optional). No patient details."
}
},
"additionalProperties": false
}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).
| Argument | Type | Description |
|---|---|---|
| typing* | object | locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers. |
{
"type": "object",
"required": [
"typing"
],
"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"
}
}
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| donor* | object | locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers. |
| recipient* | object | locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers. |
{
"type": "object",
"required": [
"recipient",
"donor"
],
"properties": {
"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"
}
}
},
"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"
}
}
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| donor* | object | locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers. |
| framework | string | |
| recipient* | object | locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers. |
{
"type": "object",
"required": [
"recipient",
"donor"
],
"properties": {
"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": {
"enum": [
"6/6",
"8/8",
"10/10",
"12/12",
"antigen"
],
"type": "string",
"default": "8/8"
},
"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"
}
}
}
},
"additionalProperties": false
}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).
| Argument | Type | Description |
|---|---|---|
| name* | string | One reported HLA allele name, any nomenclature era. An allele string only, never a patient name, medical record number or other identifier. |
{
"type": "object",
"required": [
"name"
],
"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."
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| typing | object | locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers. |
| alleles | array | A flat list of reported allele names instead of a typing. Send exactly one of typing or alleles. |
{
"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",
"items": {
"type": "string",
"maxLength": 64
},
"maxItems": 96,
"description": "A flat list of reported allele names instead of a typing. Send exactly one of typing or alleles."
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| donor* | object | Donor typing: {"typing": {...}} or {"alleles": [...]}. |
| recipient* | object | Recipient typing: {"typing": {...}} or {"alleles": [...]}. |
{
"type": "object",
"required": [
"recipient",
"donor"
],
"properties": {
"donor": {
"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",
"items": {
"type": "string",
"maxLength": 64
},
"maxItems": 96
}
},
"description": "Donor typing: {\"typing\": {...}} or {\"alleles\": [...]}.",
"additionalProperties": false
},
"recipient": {
"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",
"items": {
"type": "string",
"maxLength": 64
},
"maxItems": 96
}
},
"description": "Recipient typing: {\"typing\": {...}} or {\"alleles\": [...]}.",
"additionalProperties": false
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| to* | string | An IPD-IMGT/HLA release, like "3.40.0" (1.05.0 to the current one). |
| from* | string | An IPD-IMGT/HLA release, like "3.40.0" (1.05.0 to the current one). |
| limit | integer | Maximum items per list (default 500). |
| locus | string | One locus, like "A" or "DRB1". |
{
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"to": {
"type": "string",
"maxLength": 16,
"description": "An IPD-IMGT/HLA release, like \"3.40.0\" (1.05.0 to the current one)."
},
"from": {
"type": "string",
"maxLength": 16,
"description": "An IPD-IMGT/HLA release, like \"3.40.0\" (1.05.0 to the current one)."
},
"limit": {
"type": "integer",
"maximum": 5000,
"minimum": 1,
"description": "Maximum items per list (default 500)."
},
"locus": {
"type": "string",
"maxLength": 8,
"description": "One locus, like \"A\" or \"DRB1\"."
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| email* | string | The applicant's email address. The approval code is sent here. |
| source | string | Where the application came from, e.g. mcp (optional). |
| use_case* | string | 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. |
| institution* | string | University, hospital, institute or nonprofit the work is done at. |
| expected_volume | string | Rough call or typing volume, e.g. 'about 20,000 typings a month' (optional). |
{
"type": "object",
"required": [
"email",
"institution",
"use_case"
],
"properties": {
"email": {
"type": "string",
"maxLength": 254,
"description": "The applicant's email address. The approval code is sent here."
},
"source": {
"type": "string",
"maxLength": 120,
"description": "Where the application came from, e.g. mcp (optional)."
},
"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."
},
"institution": {
"type": "string",
"maxLength": 200,
"description": "University, hospital, institute or nonprofit the work is done at."
},
"expected_volume": {
"type": "string",
"maxLength": 120,
"description": "Rough call or typing volume, e.g. 'about 20,000 typings a month' (optional)."
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| to | string | An IPD-IMGT/HLA release, like "3.40.0" (1.05.0 to the current one). |
| from | string | An IPD-IMGT/HLA release, like "3.40.0" (1.05.0 to the current one). |
| names* | array | Allele names exactly as written in the `from` release. |
{
"type": "object",
"required": [
"names"
],
"properties": {
"to": {
"type": "string",
"maxLength": 16,
"description": "An IPD-IMGT/HLA release, like \"3.40.0\" (1.05.0 to the current one)."
},
"from": {
"type": "string",
"maxLength": 16,
"description": "An IPD-IMGT/HLA release, like \"3.40.0\" (1.05.0 to the current one)."
},
"names": {
"type": "array",
"items": {
"type": "string",
"maxLength": 64
},
"maxItems": 5000,
"minItems": 1,
"description": "Allele names exactly as written in the `from` release."
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| gl* | string | GL String to validate and normalize. Allele names and GL grammar only, never patient identifiers. |
{
"type": "object",
"required": [
"gl"
],
"properties": {
"gl": {
"type": "string",
"maxLength": 100000,
"description": "GL String to validate and normalize. Allele names and GL grammar only, never patient identifiers."
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| text* | string | 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. |
{
"type": "object",
"required": [
"text"
],
"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."
}
},
"additionalProperties": false
}