Pharmacogenomics Guidelines Mcp Server

io.github.cyanheadsPublished by GitHub account cyanheadsv0.3.0Updated Oct 30, 2026

Find pharmacogenomics guidelines, translate diplotypes, and retrieve prescribing recommendations.

The publisher's own server: Guidelines

VerifiedStreamable HTTPWeb executableKnowledge & MemoryData & Analytics

Overview

AI-generated overview

Read-only access to public CPIC/ClinPGx pharmacogenomics data: gene–drug pairs, guidelines, allele evidence, diplotype translation and prescribing…

What you can do
  • Search evaluated gene–drug pairs by gene, drug name, RxNorm/ATC code, CPIC level or testing label, with paging
  • Retrieve guideline coverage by ID, gene or drug, including related drugs and pairs
  • Translate a diplotype or HLA allele status into gene result, activity score and lookup key
  • Browse or match prescribing recommendations by drug, genotype or supplied gene results, with optional example CDS test alerts
  • Inspect allele function, evidence and population frequencies, and list genes, phenotypes and controlled vocabulary
When to use it
Useful when an assistant needs to look up pharmacogenomics evidence: which gene–drug pairs are evaluated, what a lab diplotype means, or what CPIC recommends for a given drug and genotype. Suited to research and drafting support, not to making clinical decisions on its own.
Requirements
Either the public hosted HTTP endpoint or a local process via npx (Node.js; Bun 1.4+ or Node 24+ for source builds). No API key or account. Network access to the CPIC API. Optional environment variables configure transport, host, port, endpoint path, auth mode and log level.
Before you install
Queries, including genetic results, are sent to the CPIC API, and request URLs containing them appear in responses; the hosted instance also passes them through its own server, so run a local instance for patient data. Source data may omit guideline nuances or lag updates, so linked guidelines must be checked before clinical use. A pair is not a recommendation, and omitted genes are never assumed normal. All tools are read-only and no patient records are stored.

Installation

In SourceWeft

  1. Open Pharmacogenomics Guidelines Mcp Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.cyanheads%2Fpharmacogenomics-guidelines-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "pharmacogenomics-guidelines": {
      "type": "http",
      "url": "https://pharmacogenomics-guidelines.caseyjhand.com/mcp"
    }
  }
}

README

@cyanheads/pharmacogenomics-guidelines-mcp-server

Find pharmacogenomics guidelines, translate diplotypes, and retrieve prescribing recommendations via MCP. STDIO or Streamable HTTP.

6 Tools

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

ToolDescription
pgx_search_pairsSearch evaluated gene–drug pairs by gene, drug, RxNorm/ATC identifier, CPIC level or testing label
pgx_get_guidelineRetrieve guideline coverage by ID, gene or drug, with related drugs and pairs
pgx_lookup_diplotypeTranslate a diplotype or HLA allele status into its gene result, activity score and lookup key
pgx_get_recommendationsBrowse or match source prescribing recommendations and opt-in example CDS test alerts
pgx_search_allelesInspect allele function, evidence, definition metadata and population frequencies
pgx_list_referenceList genes, gene-specific results, controlled vocabulary and input formats

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 gene is never assumed normal, negative or Indeterminate. Phenotypes, decimal activity scores and HLA allele statuses are each checked against CPIC's own values.
  • Bounded workflows:
    • 45-second deadline, at most 100 HTTP attempts, three concurrent requests, two retries per request
    • Related scans stop at 2,000 rows (drug resolution 500). Guideline lists and detail views page at the source; related counts use exact source totals, with bounded scans only when totals are missing. Past a scan cap the call fails as query_too_broad rather than returning partial results.

Agent-friendly output:

  • Provenance: exact deduplicated request URLs, access timestamp, returned row versions, and license and policy links. Each version uses an RFC 6901 JSON Pointer into the result and a requestIndex into requestUrls. API v1 names the interface, not a database release.
  • Explicit outcomes: recommendation status, per-gene geneResolutions, incompleteMatches, and typed error reasons with recovery text.
  • Lossless text output: content[] carries the complete result as JSON with one clickable link per distinct destination in each rendered block, matching structuredContent. effectiveQuery, notices and page (total, nextOffset) explain every result.

Source attribution and clinical limitations

Data comes from the CPIC Database and ClinPGx. The CPIC data license and the ClinPGx usage policy cover the source data; this repository's Apache-2.0 license covers its code.

The database tables can omit guideline nuances or lag behind guideline updates, so check each linked guideline before clinical use. Results apply only to their stated genes, drugs, populations and indications, and treatment decisions remain with the clinician and patient. The server stores no patient records, but genetic queries are sent to the CPIC API, and the request URLs, which contain them, appear in responses.

Getting started

Connect to the hosted instance, no install:

sh
claude mcp add --transport http pharmacogenomics-guidelines-mcp-server https://pharmacogenomics-guidelines.caseyjhand.com/mcp

Queries to the hosted instance pass through its server on the way to the CPIC API. For patient data, run your own instance.

Or run it locally:

sh
claude mcp add pharmacogenomics-guidelines-mcp-server -- npx -y @cyanheads/pharmacogenomics-guidelines-mcp-server

For other clients, add this to the MCP config file:

json
{  "mcpServers": {    "pharmacogenomics-guidelines-mcp-server": {      "command": "npx",      "args": ["-y", "@cyanheads/pharmacogenomics-guidelines-mcp-server"]    }  }}

No API key is needed. For Docker or a source build, see Running the server.

Configuration

No server-specific environment variables are required.

VariableDescriptionDefault
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_HOSTHTTP bind address.127.0.0.1
MCP_HTTP_PORTHTTP server port.3010
MCP_HTTP_ENDPOINT_PATHMCP endpoint path./mcp
MCP_SESSION_MODEHTTP session mode: stateless, stateful or auto.stateless
MCP_AUTH_MODEAuthentication: none, jwt or oauth.none
MCP_LOG_LEVELLog level (debug, info, warning, error, etc.).debug
OTEL_ENABLEDEnable OpenTelemetry.false

See .env.example for the common framework overrides.

Running the server

Local development

Requires Bun v1.4.0 or higher (or Node.js v24+), and network access to https://api.cpicpgx.org.

  • Clone and install:

    sh
    git clone https://github.com/cyanheads/pharmacogenomics-guidelines-mcp-server.gitcd pharmacogenomics-guidelines-mcp-server && bun installcp .env.example .env   # optional: adjust transport, logging, or telemetry settings

  • Build and run the production version:

    sh
    # One-time buildbun run rebuild
# Run the built serverbun run start:http# orbun run start:stdio

  • Run checks and tests:

    sh
    bun run devcheck  # Lints, formats, type-checks, and morebun run test      # Runs the test suite

Docker

sh
docker run --rm -p 3010:3010 ghcr.io/cyanheads/pharmacogenomics-guidelines-mcp-server:latest

The image defaults to HTTP transport, stateless session mode, and logs to /var/log/pharmacogenomics-guidelines-mcp-server. To run it over stdio from an MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/pharmacogenomics-guidelines-mcp-server:latest"]. To build locally, docker build -t pharmacogenomics-guidelines-mcp-server .; OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

DirectoryPurpose
src/mcp-server/tools/definitionsThe six tool definitions and the allToolDefinitions registry.
src/mcp-server/tools/sharedPaging schemas and lossless Markdown rendering.
src/services/cpicFixed-host CPIC requests, source record schemas, discovery, evidence and recommendation matching.
skillsThe published agent skill, served over MCP via createApp({ skills }).
tests/unitService, tool contract, boundary and formatter tests.
tests/integrationStdio server check of the published skill resource.
tests/scriptsBundle cleaner and packaging linter selector tests.
docsDesign contract and generated directory tree.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

  • Handlers throw, framework catches — no try/catch in tool logic
  • Use ctx.log for logging, ctx.state for storage
  • Register new tools in allToolDefinitions (src/mcp-server/tools/definitions/index.ts), which src/index.ts passes to createApp()
  • Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

sh
bun run devcheckbun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Source: README.md at commit 743b7db

Tools

6

pgx_search_pairs

Search evaluated gene–drug pairs

Search evaluated gene–drug pairs by gene, literal drug-name substring, exact drug/RxNorm/ATC identifiers, evaluation level or testing label. Filters combine with AND; identifiers never fall back to name-only search. Results include source drug identifiers and guideline links for pgx_get_guideline. A pair evaluation is not a prescribing recommendation. Follow nextOffset to continue.

ParametersatcIdlimitdrugIdoffsetdrugNamerxnormIdcpicLevelgeneSymbolpgxTestingprovisionalincludeRetiredusedForRecommendation

pgx_get_guideline

Get guideline coverage

Retrieve guideline coverage by source ID, exact gene symbol or exact drug name/ID. Default summary pages complete guideline records with exact drugCount/pairCount. view=drugs or pairs requires by=id and pages only that related collection, retaining its guideline descriptor. Ambiguous drug names page candidates for retry with drugId. Follow page.nextOffset; the 24,000-byte soft budget cuts only between complete rows, with oversizedRow for an indivisible exception. Missing coverage is found=false. Consult linked guidelines before clinical use.

ParametersbyrequiredviewlimitdrugIdoffsetdrugNamegeneSymbolguidelineId

pgx_lookup_diplotype

Look up diplotype

Translate a CPIC-supported diplotype or allele-status result for one gene. Supply geneSymbol and exact diplotype notation, including star alleles, named HLA positive/negative statuses, or non-star sequences; use pgx_search_alleles and pgx_list_reference with topic phenotypes to inspect supported values. Exact lookup precedes bounded reverse-order or status aliases. Multiple source rows remain ambiguous; no activity score or missing gene result is inferred.

ParametersdiplotyperequiredgeneSymbolrequired

pgx_get_recommendations

Get recommendations

Browse CPIC recommendations in drug mode with one exact drugName or drugId. Match across drugs in results mode with geneResults or geneSymbol plus phenotype/activityScore, or genotype mode with 1–10 uniquely resolved gene/diplotype entries. Both matching modes accept an optional drug. Optional view=test_alerts selects complete example CDS alerts instead of recommendations, without joins; default view=recommendations. Alert records retain ordered alerttext, No CDS and n/a. Use pgx_list_reference topic phenotypes for source values. Every matched prerequisite must be explicit; omitted genes are never normal, negative or No Result. Preserve populations, scores, classifications and source text. Follow page.nextOffset and incompletePage.nextOffset independently for the selected collection and missing-gene diagnostics; consult source guidelines before clinical use.

ParametersmoderequiredviewlimitdrugIdoffsetdrugNamegenotypephenotypegeneSymbolpopulationgeneResultsactivityScore+2 more

pgx_search_alleles

Search alleles

Inspect CPIC allele function, evidence, definition metadata and complete population frequencies for geneSymbol. Name matches literally first, then a matching gene prefix before a star allele may be removed; clinicalFunctionalStatus matches literal text case-insensitively. Discover genes with pgx_list_reference. Definitions are metadata, not variant interpretation. Frequencies are source fractions; inferred frequencies are not observations and do not establish individual risk. Pages have a 24,000-byte complete-result soft budget; an indivisible exception sets oversizedRow. Continue with page.nextOffset.

ParametersnamelimitoffsetgeneSymbolrequiredclinicalFunctionalStatus

pgx_list_reference

List pharmacogenomics reference values

Inspect gene symbols, gene-specific source results, CPIC levels, ClinPGx testing labels, recommendation classifications and input formats. phenotypes requires geneSymbol and preserves distinct activity-score rows, frequencies and consultation text. Live genes/phenotypes support paging; static topics return their complete vocabulary without upstream requests. Use returned values in subsequent discovery, diplotype and recommendation calls.

ParameterslimittopicrequiredoffsetgeneSymbol

Version history

3
  1. v0.3.0LatestOct 29, 2026
  2. v0.2.1Oct 25, 2026
  3. v0.2.0Oct 20, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Guidelines integrations

Guidelines

site.guidelinesOfficial publisher

A remote, read-only MCP server that gives an assistant access to your Guidelines brands, including colors, fonts, logos and Guide pages as markdown.

Streamable HTTPWeb executableAuth
Media & DesignCredential requiredOct 24, 2026

Brandsystem MCP — Brand Guidelines for AI

Published by GitHub account Brandcode-Studio

Turns existing brand material (website, PDF, Figma, hosted brand) into a local .brand runtime of tokens, voice rules and checks that assistants can apply.

STDIODesktop only
Knowledge & Memory12 toolsNov 2, 2026