Pharmacogenomics Guidelines MCP Server

@cyanheads/pharmacogenomics-guidelines-mcp-server Find pharmacogenomics guidelines, translate diplotypes, and retrieve prescribing recommendations via MCP. STDIO or Streamable HTTP. 6 Tools

Public Hosted Server: https://pharmacogenomics-guidelines.caseyjhand.com/mcp

Overview

Clinical pharmacogenomics evidence from the public CPIC Database API: evaluated gene–drug pairs, guidelines, allele function and frequency, diplotype-to-phenotype translation, and prescribing recommendations, with ClinPGx testing labels and guideline links. You can discover pairs, translate a patient's diplotype, and browse recommendations or match them against explicitly supplied gene results. All six tools are read-only, need no API key, and run as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Agent skill

skills/pharmacogenomics-guidelines-guide is a published Agent Skill for the agents calling these tools: where each identifier comes from, diplotype notation, and the gates between a lab result and a recommendation. Plugin installs and the .mcpb bundle load it directly; MCP clients read it as the skill://pharmacogenomics-guidelines-guide/SKILL.md resource.

Capability reference

pgx_search_pairs tool

• Optional filters, combined with AND: geneSymbol, drugName (literal substring), drugId, rxnormId, atcId (exact code, no hierarchy expansion), cpicLevel, provisional, pgxTesting and usedForRecommendation.
• RxNorm/ATC prefixes and ATC letters accept any casing in both advertised schemas and runtime validation. Outer whitespace is ignored; blank identifiers are unset.
• limit defaults to 25; positive safe integers above 100 clamp to 100 with a notice. Continue from page.nextOffset.
• Returns complete pair records, each with its drug record and guideline link. Retired pairs appear only with includeRetired: true or cpicLevel: "Retired".

pgx_get_guideline tool

• Three lookup modes; selectors from other modes are rejected:
• by: "id" with guidelineId
• by: "gene" with geneSymbol
• by: "drug" with exactly one of drugName (exact, case-insensitive) or drugId
• Default view: "summary" pages complete guideline records with exact drugCount and pairCount. view: "drugs" or "pairs" requires by: "id", retains the guideline descriptor, and pages the selected top-level collection; the other collection is omitted.
• limit defaults to 25; positive safe integers above 100 clamp to 100 with a notice. Follow page.nextOffset. Pages use a 24,000-byte soft budget across both response surfaces and enrichment, cutting only between complete rows. One indivisible oversized row sets oversizedRow: true with a notice.
• No coverage returns found: false. An ambiguous drug name returns paged candidates; page, shown and truncated then describe those candidates. Retry with a drugId from that list.

pgx_lookup_diplotype tool

• Takes geneSymbol plus a source-supported diplotype, in either allele order:
• star alleles (*1/*2, *1x2/*4)
• HLA allele status (*57:01 positive)
• non-star notation (c.1905+1G>A (*2A)/Reference)
• Returns found, matchedDiplotype, guidance, and every matching source record with its gene result, activity score, EHR priority and lookup key.
• Several matching records are left ambiguous, never resolved to one. No result is calculated.

pgx_get_recommendations tool

• Omit view or use view: "recommendations" for prescribing recommendations. view: "test_alerts" selects CPIC's example CDS language with the same drug, genotype, result, population and paging selectors; it does not fetch recommendations or join guidelines.
• mode: "drug" takes exactly one of drugName (exact, case-insensitive) or drugId.
• On its own, or with geneSymbol or population, it browses (exploratory).
• To match, add phenotype or activityScore. These need geneSymbol when the drug's recommendations involve several genes.
• Alternatively, add a geneResults map: 1–10 genes, each { kind: "phenotype" | "activityScore" | "alleleStatus", value }.
• mode: "genotype" takes genotype: 1–10 gene → diplotype entries, each of which must resolve uniquely. An optional drug selector narrows the results.
• mode: "results" discovers across drugs from geneResults, or geneSymbol with one phenotype/activityScore. An optional drug selector narrows the results. Unrelated panel genes do not exclude a recommendation; conflicting results for its prerequisites do.
• Source gene lookupmethod determines accepted result kinds: PHENOTYPE permits phenotype; ACTIVITY_SCORE permits phenotype or activityScore; ALLELE_STATUS permits alleleStatus. Values are validated against source result/score fields. Phenotypes never become calculated scores. Inspect pgx_list_reference topics genes and phenotypes before matching.
• All modes accept an exact population, limit (default 10) and offset. Positive safe-integer limits above 50 clamp to 50 with a notice. incompleteLimit (default 25) independently clamps above 100; incompleteOffset pages missing-gene diagnostics through incompletePage.nextOffset.
• status is exploratory, matched, no_match, incomplete or unresolved. Drug and results matching require at least one overlapping supplied gene, reject conflicts on overlapping prerequisites, and ignore unrelated validated panel genes. A row matches only when every gene in its lookup key has an explicit result. incompleteMatches lists the rows that need more genes, with their missingGenes and without prescribing text.
• Empty-result notices distinguish unresolved drugs, absent recommendation tables, population mismatches and past-end pages. Where source coverage exists, a no-table notice links the guideline for consultation.
• Alert view returns complete source records in alerts, including ordered alerttext, singular phenotype, lookup keys, allele statuses, scores, populations and versions. No CDS, n/a, sparse fields and explicit source No Result rows remain intact. Omitted genetics never become No Result. Missing prerequisites appear only as { testAlertId, drugId, missingGenes } in incompleteAlerts, without alert text. items and incompleteMatches remain empty; page and incompletePage describe alerts and diagnostics. Default responses omit both alert fields.

pgx_search_alleles tool

• Requires geneSymbol. name matches literally first, then retries a matching gene-prefixed star allele without that prefix. clinicalFunctionalStatus matches literal text case-insensitively. Returned source spelling stays unchanged; effectiveQuery shows the allele name used.
• limit defaults to 25; positive safe integers above 100 clamp to 100 with a notice. Nonpositive, fractional and unsafe limits fail before fetching. offset is a nonnegative safe integer.
• The 24,000-byte soft budget measures the entire serialized tool result, including both response surfaces and enrichment. It cuts only between complete alleles, keeping every frequency row. An indivisible oversized first row sets oversizedRow: true with a notice. Follow page.nextOffset to reconstruct the remaining rows.
• Returns allele function and evidence with definition metadata and populationFrequencies. Frequencies stay as source fractions, missing values stay missing, and inferred frequencies are flagged as inferred.

pgx_list_reference tool

• topic is one of:
• genes — optional geneSymbol filter
• phenotypes — requires geneSymbol
• cpic_levels, pgx_testing, classifications, input_formats
• The two live topics (genes, phenotypes) page with limit (default 25) and offset; positive safe-integer limits above 100 clamp to 100 with a notice. They return full gene and gene-result records, including distinct activity scores, frequencies and consultation text.
• Static topics return their whole vocabulary without calling the CPIC API. They reject geneSymbol and carry a verificationDate.

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

CPIC-specific:

• One lookup chain: reference values → pairs → guidelines → allele and diplotype evidence → recommendations
• CPIC evaluation levels, ClinPGx testing labels and recommendation classifications are kept separate. A testing label is not an FDA label, and an evaluated pair is not a recommendation.
• Matching uses only results you supply. An omitted ge