pharmacogenomics-guidelines-mcp-server
An open-source MCP server that provides read-only access to clinical pharmacogenomics evidence from the public CPIC Database API. It allows agents to search evaluated gene-drug pairs, retrieve guideline coverage, translate diplotypes to phenotypes, and browse prescribing recommendations with ClinPGx testing labels.
Endpoint and access
No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.
MCP endpoint (Streamable HTTP)
https://pharmacogenomics-guidelines.caseyjhand.com/mcpWhat you can do with it
- Search evaluated gene-drug pairs by gene, drug name, or identifier
- Translate a patient's diplotype into gene result and activity score
- Retrieve guideline coverage and prescribing recommendations
- Inspect allele function, evidence, and population frequencies
Source and maintenance
Community listingRegistry 0.3.0
- Maintenance checked
Protocol and capabilities
- Server
- pharmacogenomics-guidelines-mcp-server 0.3.0
- MCP protocol
- 2025-06-18
- Tools
- 6 advertised
- Resources
- 1 advertised
- Resource templates
- 1 advertised
- Prompts
- 0 advertised
Server-advertised capabilities
{
"tools": {
"listChanged": true
},
"logging": {},
"prompts": {
"listChanged": true
},
"resources": {
"subscribe": true,
"listChanged": true
},
"extensions": {
"io.modelcontextprotocol/skills": {
"directoryRead": true
}
}
}Server-provided instructions
Untrusted server output shown for inspection. It is not Koskamo guidance and is excluded from knowledge search.
Tools
6 advertised
pgx_search_pairs — Search evaluated gene–drug pairs
Advertised read-onlyOpen-world
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.
pgx_search_pairs input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"atcId": {
"type": "string",
"pattern": "^(?:\\s*|\\s*(?:[Aa][Tt][Cc]:)?[A-Za-z\\d]{1,7}\\s*)$",
"description": "Exact ATC code (1–7 letters/digits) in any casing, optionally prefixed ATC: in any casing; outer whitespace is ignored and blank means unset."
},
"limit": {
"type": "integer",
"default": 25,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Positive safe-integer row limit; values above 100 are clamped to 100 with a notice (default 25)."
},
"drugId": {
"type": "string",
"maxLength": 200,
"description": "Exact drugId returned by pgx_search_pairs; blank means unset."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based offset; use nextOffset to continue (default 0)."
},
"drugName": {
"type": "string",
"maxLength": 200,
"description": "Literal case-insensitive drug-name substring; blank means unset."
},
"rxnormId": {
"type": "string",
"pattern": "^(?:\\s*|\\s*(?:[Rr][Xx][Nn][Oo][Rr][Mm]:)?\\d+\\s*)$",
"description": "Decimal RxNorm ID, optionally prefixed RxNorm: in any casing; outer whitespace is ignored and blank means unset."
},
"cpicLevel": {
"enum": [
"A",
"A/B",
"B",
"B/C",
"C",
"C/D",
"D",
"Retired"
],
"type": "string",
"description": "Exact source CPIC evaluation level, not a prescribing recommendation."
},
"geneSymbol": {
"type": "string",
"maxLength": 100,
"description": "Exact gene symbol, case-insensitive input; blank means unset."
},
"pgxTesting": {
"enum": [
"Actionable PGx",
"Informative PGx",
"No Clinical PGx",
"Testing Recommended",
"Testing Required"
],
"type": "string",
"description": "ClinPGx label-annotation testing level; not an FDA label."
},
"provisional": {
"type": "boolean",
"description": "Filter by source provisional flag."
},
"includeRetired": {
"type": "boolean",
"default": false,
"description": "Include Retired pairs; also included when cpicLevel is Retired."
},
"usedForRecommendation": {
"enum": [
"Yes",
"No"
],
"type": "string",
"description": "Whether the source marks the pair as used for a recommendation."
}
},
"additionalProperties": false
}pgx_search_pairs output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"items",
"page",
"provenance",
"effectiveQuery",
"notices",
"truncated",
"shown",
"cap"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Effective public page limit."
},
"page": {
"type": "object",
"required": [
"limit",
"offset",
"returned",
"total",
"nextOffset"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Effective requested page size."
},
"total": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Exact filtered source count, or null when unavailable."
},
"offset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Requested zero-based offset."
},
"returned": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of rows returned on this page."
},
"nextOffset": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Offset for the next page, or null when no rows remain."
}
},
"description": "Source pagination metadata.",
"additionalProperties": false
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"query_too_broad",
"upstream_query_rejected",
"upstream_rate_limited",
"upstream_unavailable"
],
"description": "Machine-readable failure mode. Declared by this tool: `query_too_broad`: A bounded source scan or workflow work budget is exceeded. `upstream_query_rejected`: CPIC rejects the generated query. `upstream_rate_limited`: CPIC returns HTTP 429. `upstream_unavailable`: CPIC is unavailable or returns a maintenance page. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"pairid",
"drug"
],
"properties": {
"drug": {
"anyOf": [
{
"type": "object",
"required": [
"drugid",
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Original source name."
},
"atcid": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Source text list in original order; nullable or absent."
},
"drugid": {
"type": "string",
"description": "Exact source drug identifier."
},
"umlscui": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"version": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Source integer; nullable or absent."
},
"rxnormid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"clinpgxid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"flowchart": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"drugbankid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"guidelineid": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Source integer; nullable or absent."
}
},
"description": "Source drug record.",
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Complete related source drug, or null when the pair has no drug identifier."
},
"pmids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Source text list in original order; nullable or absent."
},
"drugid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"pairid": {
"type": "integer",
"description": "Source record identifier."
},
"drugname": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"cpiclevel": {
"type": [
"string",
"null"
],
"description": "CPIC-assigned pair evaluation level; not a prescribing recommendation."
},
"genesymbol": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"pgxtesting": {
"type": [
"string",
"null"
],
"description": "ClinPGx label-annotation testing level; distinct from CPIC evaluation."
},
"provisional": {
"type": [
"boolean",
"null"
],
"description": "Source flag; nullable or absent."
},
"clinpgxlevel": {
"type": [
"string",
"null"
],
"description": "Top ClinPGx Summary Annotation level for this pair."
},
"guidelineurl": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"guidelinename": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"usedforrecommendation": {
"type": [
"string",
"null"
],
"description": "Source pair recommendation-use label (Yes, No, or n/a); not prescribing advice."
}
},
"description": "Evaluated pair with its related source drug.",
"additionalProperties": {}
},
"description": "Complete evaluated pairs and related drugs."
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of returned rows, equal to page.returned."
},
"notices": {
"type": "array",
"items": {
"type": "string",
"description": "Source or workflow notice."
},
"description": "Notices about this result; empty when none apply."
},
"truncated": {
"type": "boolean",
"description": "Whether more matching rows remain after this page."
},
"provenance": {
"type": "object",
"required": [
"source",
"primarySourceUrl",
"apiVersion",
"requestUrls",
"licenseUrl",
"policyUrl",
"rowVersions",
"accessedAt"
],
"properties": {
"source": {
"type": "string",
"const": "CPIC Database",
"description": "Source database."
},
"policyUrl": {
"type": "string",
"description": "ClinPGx usage policy URL."
},
"accessedAt": {
"type": "string",
"description": "UTC access timestamp for live requests."
},
"apiVersion": {
"type": "string",
"const": "v1",
"description": "API interface version, not a database release."
},
"licenseUrl": {
"type": "string",
"description": "Source licence URL."
},
"requestUrls": {
"type": "array",
"items": {
"type": "string"
},
"description": "Exact requests made during this workflow."
},
"rowVersions": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"requestIndex",
"version"
],
"properties": {
"path": {
"type": "string",
"description": "RFC 6901 JSON Pointer to the returned version-bearing record."
},
"version": {
"type": "number",
"description": "Source row version."
},
"requestIndex": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Index in requestUrls of the source request."
}
},
"description": "Version of one retrieved source record.",
"additionalProperties": false
},
"description": "Available source record versions."
},
"primarySourceUrl": {
"type": "string",
"const": "https://www.clinpgx.org/",
"description": "Primary clinical source."
}
},
"description": "Live source attribution and retrieval details.",
"additionalProperties": false
},
"effectiveQuery": {
"type": "object",
"required": [
"includeRetired",
"limit",
"offset"
],
"properties": {
"atcId": {
"type": "string",
"pattern": "^(?:\\s*|\\s*(?:[Aa][Tt][Cc]:)?[A-Za-z\\d]{1,7}\\s*)$",
"description": "Exact ATC code (1–7 letters/digits) in any casing, optionally prefixed ATC: in any casing; outer whitespace is ignored and blank means unset."
},
"limit": {
"type": "integer",
"default": 25,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Positive safe-integer row limit; values above 100 are clamped to 100 with a notice (default 25)."
},
"drugId": {
"type": "string",
"maxLength": 200,
"description": "Exact drugId returned by pgx_search_pairs; blank means unset."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based offset; use nextOffset to continue (default 0)."
},
"drugName": {
"type": "string",
"maxLength": 200,
"description": "Literal case-insensitive drug-name substring; blank means unset."
},
"rxnormId": {
"type": "string",
"pattern": "^(?:\\s*|\\s*(?:[Rr][Xx][Nn][Oo][Rr][Mm]:)?\\d+\\s*)$",
"description": "Decimal RxNorm ID, optionally prefixed RxNorm: in any casing; outer whitespace is ignored and blank means unset."
},
"cpicLevel": {
"enum": [
"A",
"A/B",
"B",
"B/C",
"C",
"C/D",
"D",
"Retired"
],
"type": "string",
"description": "Exact source CPIC evaluation level, not a prescribing recommendation."
},
"geneSymbol": {
"type": "string",
"maxLength": 100,
"description": "Exact gene symbol, case-insensitive input; blank means unset."
},
"pgxTesting": {
"enum": [
"Actionable PGx",
"Informative PGx",
"No Clinical PGx",
"Testing Recommended",
"Testing Required"
],
"type": "string",
"description": "ClinPGx label-annotation testing level; not an FDA label."
},
"provisional": {
"type": "boolean",
"description": "Filter by source provisional flag."
},
"includeRetired": {
"type": "boolean",
"default": false,
"description": "Include Retired pairs; also included when cpicLevel is Retired."
},
"usedForRecommendation": {
"enum": [
"Yes",
"No"
],
"type": "string",
"description": "Whether the source marks the pair as used for a recommendation."
}
},
"description": "Normalized filters and effective paging.",
"additionalProperties": false
}
},
"additionalProperties": false
}pgx_search_pairs annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}pgx_get_guideline — Get guideline coverage
Advertised read-onlyOpen-world
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.
pgx_get_guideline input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"by"
],
"properties": {
"by": {
"enum": [
"id",
"gene",
"drug"
],
"type": "string",
"description": "id requires guidelineId; gene requires geneSymbol; drug requires exactly one exact drugName or drugId. Other selectors must be omitted."
},
"view": {
"enum": [
"summary",
"drugs",
"pairs"
],
"type": "string",
"default": "summary",
"description": "Summary pages guideline descriptors; drugs or pairs requires by=id and pages only that related collection."
},
"limit": {
"type": "integer",
"default": 25,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Positive safe-integer row limit; values above 100 are clamped to 100 with a notice (default 25)."
},
"drugId": {
"type": "string",
"maxLength": 200,
"description": "Exact drugId returned by pgx_search_pairs; blank means unset."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based offset; use nextOffset to continue (default 0)."
},
"drugName": {
"type": "string",
"maxLength": 200,
"description": "Exact case-insensitive source drug name for by=drug; blank means unset."
},
"geneSymbol": {
"type": "string",
"maxLength": 100,
"description": "Gene symbol for by=gene; blank means unset."
},
"guidelineId": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Positive source guideline ID from pgx_get_guideline by=gene or by=drug results; no valid ID range is inferred.",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
}pgx_get_guideline output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"view",
"oversizedRow",
"page",
"found",
"guidelines",
"candidates",
"guidance",
"clinicalCaveat",
"provenance",
"effectiveQuery",
"notices",
"truncated",
"shown",
"cap"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Effective public page limit."
},
"page": {
"type": "object",
"required": [
"limit",
"offset",
"returned",
"total",
"nextOffset"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Effective requested page size."
},
"total": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Exact filtered source count, or null when unavailable."
},
"offset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Requested zero-based offset."
},
"returned": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of rows returned on this page."
},
"nextOffset": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Offset for the next page, or null when no rows remain."
}
},
"description": "Source pagination metadata.",
"additionalProperties": false
},
"view": {
"enum": [
"summary",
"drugs",
"pairs"
],
"type": "string",
"description": "Selected guideline view."
},
"drugs": {
"type": "array",
"items": {
"type": "object",
"required": [
"drugid",
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Original source name."
},
"atcid": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Source text list in original order; nullable or absent."
},
"drugid": {
"type": "string",
"description": "Exact source drug identifier."
},
"umlscui": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"version": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Source integer; nullable or absent."
},
"rxnormid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"clinpgxid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"flowchart": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"drugbankid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"guidelineid": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Source integer; nullable or absent."
}
},
"description": "Source drug record.",
"additionalProperties": {}
},
"description": "Selected drugs page; omitted in other views."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_selector",
"query_too_broad",
"upstream_query_rejected",
"upstream_rate_limited",
"upstream_unavailable"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_selector`: Selectors are missing, conflicting or mixed across modes. `query_too_broad`: A bounded source scan or workflow work budget is exceeded. `upstream_query_rejected`: CPIC rejects the generated query. `upstream_rate_limited`: CPIC returns HTTP 429. `upstream_unavailable`: CPIC is unavailable or returns a maintenance page. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"found": {
"type": "boolean",
"description": "Whether guideline coverage was found."
},
"pairs": {
"type": "array",
"items": {
"type": "object",
"required": [
"pairid"
],
"properties": {
"pmids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Source text list in original order; nullable or absent."
},
"drugid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"pairid": {
"type": "integer",
"description": "Source record identifier."
},
"drugname": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"cpiclevel": {
"type": [
"string",
"null"
],
"description": "CPIC-assigned pair evaluation level; not a prescribing recommendation."
},
"genesymbol": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"pgxtesting": {
"type": [
"string",
"null"
],
"description": "ClinPGx label-annotation testing level; distinct from CPIC evaluation."
},
"provisional": {
"type": [
"boolean",
"null"
],
"description": "Source flag; nullable or absent."
},
"clinpgxlevel": {
"type": [
"string",
"null"
],
"description": "Top ClinPGx Summary Annotation level for this pair."
},
"guidelineurl": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"guidelinename": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"usedforrecommendation": {
"type": [
"string",
"null"
],
"description": "Source pair recommendation-use label (Yes, No, or n/a); not prescribing advice."
}
},
"description": "Evaluated gene–drug pair.",
"additionalProperties": {}
},
"description": "Selected pairs page; omitted in other views."
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of returned rows, equal to page.returned."
},
"notices": {
"type": "array",
"items": {
"type": "string",
"description": "Source or workflow notice."
},
"description": "Notices about this result; empty when none apply."
},
"guidance": {
"type": "string",
"description": "Next lookup step when missing or ambiguous; empty when found."
},
"truncated": {
"type": "boolean",
"description": "Whether more matching rows remain after this page."
},
"candidates": {
"type": "array",
"items": {
"type": "object",
"required": [
"drugid",
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Original source name."
},
"atcid": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Source text list in original order; nullable or absent."
},
"drugid": {
"type": "string",
"description": "Exact source drug identifier."
},
"umlscui": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"version": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Source integer; nullable or absent."
},
"rxnormid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"clinpgxid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"flowchart": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"drugbankid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"guidelineid": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Source integer; nullable or absent."
}
},
"description": "Source drug record.",
"additionalProperties": {}
},
"description": "Paged exact drug-name candidates when resolution is ambiguous; page and shown then refer to candidates."
},
"guidelines": {
"type": "array",
"items": {
"type": "object",
"required": [
"record",
"drugCount",
"pairCount"
],
"properties": {
"record": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "integer",
"description": "Source record identifier."
},
"url": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"name": {
"type": "string",
"description": "Original source name."
},
"genes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Source text list in original order; nullable or absent."
},
"version": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Source integer; nullable or absent."
},
"clinpgxid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"notesonusage": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
}
},
"description": "Complete source guideline.",
"additionalProperties": {}
},
"drugCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Exact number of related source drugs."
},
"pairCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Exact number of pairs linked by guideline URL."
}
},
"description": "Complete guideline record with exact related-record counts.",
"additionalProperties": false
},
"description": "Paged complete guideline descriptors, or the retained descriptor for a related view."
},
"provenance": {
"type": "object",
"required": [
"source",
"primarySourceUrl",
"apiVersion",
"requestUrls",
"licenseUrl",
"policyUrl",
"rowVersions",
"accessedAt"
],
"properties": {
"source": {
"type": "string",
"const": "CPIC Database",
"description": "Source database."
},
"policyUrl": {
"type": "string",
"description": "ClinPGx usage policy URL."
},
"accessedAt": {
"type": "string",
"description": "UTC access timestamp for live requests."
},
"apiVersion": {
"type": "string",
"const": "v1",
"description": "API interface version, not a database release."
},
"licenseUrl": {
"type": "string",
"description": "Source licence URL."
},
"requestUrls": {
"type": "array",
"items": {
"type": "string"
},
"description": "Exact requests made during this workflow."
},
"rowVersions": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"requestIndex",
"version"
],
"properties": {
"path": {
"type": "string",
"description": "RFC 6901 JSON Pointer to the returned version-bearing record."
},
"version": {
"type": "number",
"description": "Source row version."
},
"requestIndex": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Index in requestUrls of the source request."
}
},
"description": "Version of one retrieved source record.",
"additionalProperties": false
},
"description": "Available source record versions."
},
"primarySourceUrl": {
"type": "string",
"const": "https://www.clinpgx.org/",
"description": "Primary clinical source."
}
},
"description": "Live source attribution and retrieval details.",
"additionalProperties": false
},
"oversizedRow": {
"type": "boolean",
"description": "Whether one complete indivisible row exceeds the soft byte budget."
},
"clinicalCaveat": {
"type": "string",
"const": "CPIC database/API tables may omit guideline nuances and may lag guideline updates. Consult the linked guideline and its updates before clinical use. Recommendations are limited to their stated genes, drugs, populations, and indications; treatment decisions remain with the clinician and patient.",
"description": "Clinical qualification for source guidance."
},
"effectiveQuery": {
"type": "object",
"required": [
"view",
"by",
"limit",
"offset"
],
"properties": {
"by": {
"enum": [
"id",
"gene",
"drug"
],
"type": "string",
"description": "id requires guidelineId; gene requires geneSymbol; drug requires exactly one exact drugName or drugId. Other selectors must be omitted."
},
"view": {
"enum": [
"summary",
"drugs",
"pairs"
],
"type": "string",
"default": "summary",
"description": "Summary pages guideline descriptors; drugs or pairs requires by=id and pages only that related collection."
},
"limit": {
"type": "integer",
"default": 25,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Positive safe-integer row limit; values above 100 are clamped to 100 with a notice (default 25)."
},
"drugId": {
"type": "string",
"maxLength": 200,
"description": "Exact drugId returned by pgx_search_pairs; blank means unset."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based offset; use nextOffset to continue (default 0)."
},
"drugName": {
"type": "string",
"maxLength": 200,
"description": "Exact case-insensitive source drug name for by=drug; blank means unset."
},
"geneSymbol": {
"type": "string",
"maxLength": 100,
"description": "Gene symbol for by=gene; blank means unset."
},
"guidelineId": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Positive source guideline ID from pgx_get_guideline by=gene or by=drug results; no valid ID range is inferred.",
"exclusiveMinimum": 0
}
},
"description": "Normalized guideline selectors and effective page bounds.",
"additionalProperties": false
}
},
"additionalProperties": false
}pgx_get_guideline annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}pgx_lookup_diplotype — Look up diplotype
Advertised read-onlyOpen-world
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.
pgx_lookup_diplotype input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"geneSymbol",
"diplotype"
],
"properties": {
"diplotype": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "Exact source diplotype or allele-specific status, such as *1/*2 or *15:02 positive."
},
"geneSymbol": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Gene symbol, such as CYP2C19 or HLA-B; outer whitespace is ignored."
}
},
"additionalProperties": false
}pgx_lookup_diplotype output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"found",
"geneSymbol",
"inputDiplotype",
"matchedDiplotype",
"records",
"guidance",
"provenance",
"effectiveQuery",
"notices"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_selector",
"query_too_broad",
"upstream_query_rejected",
"upstream_rate_limited",
"upstream_unavailable"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_selector`: A required selector is blank after normalization. `query_too_broad`: An internal bounded scan or attempt budget is exceeded. `upstream_query_rejected`: CPIC rejects the generated query. `upstream_rate_limited`: CPIC rate limits requests. `upstream_unavailable`: The source is unavailable or returns maintenance HTML. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"found": {
"type": "boolean",
"description": "Whether at least one source row matched."
},
"notices": {
"type": "array",
"items": {
"type": "string",
"description": "Source or workflow notice."
},
"description": "Notices about this result; empty when none apply."
},
"records": {
"type": "array",
"items": {
"type": "object",
"required": [
"genesymbol",
"diplotype"
],
"properties": {
"diplotype": {
"type": "string",
"description": "Exact source diplotype or allele-status notation."
},
"function1": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"function2": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"lookupkey": {
"anyOf": [
{
"type": "object",
"description": "Source gene symbols mapped to exact source strings.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Normalized source gene result key for recommendation or test-alert lookup."
},
"generesult": {
"type": [
"string",
"null"
],
"description": "Gene phenotype or allele-status result according to the gene lookup method."
},
"genesymbol": {
"type": "string",
"description": "Source HGNC gene symbol."
},
"description": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"ehrpriority": {
"type": [
"string",
"null"
],
"description": "Source EHR Priority Result; not an inferred risk score."
},
"diplotypekey": {
"anyOf": [
{
"type": "object",
"description": "Source gene symbols mapped to allele names and copy counts.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "integer"
}
}
},
{
"type": "null"
}
],
"description": "Original source allele-count key, null, or omitted."
},
"activityvalue1": {
"type": [
"string",
"null"
],
"description": "Source activity assignment for allele slot 1."
},
"activityvalue2": {
"type": [
"string",
"null"
],
"description": "Source activity assignment for allele slot 2."
},
"consultationtext": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"totalactivityscore": {
"type": [
"string",
"null"
],
"description": "Source total diplotype activity-score string; never inferred from missing slots."
}
},
"description": "Source diplotype result and lookup keys.",
"additionalProperties": {}
},
"description": "Every matching source row; multiple rows are ambiguous."
},
"guidance": {
"type": "string",
"description": "Recovery guidance for missing or ambiguous source rows."
},
"geneSymbol": {
"type": "string",
"description": "Normalized supplied gene symbol."
},
"provenance": {
"type": "object",
"required": [
"source",
"primarySourceUrl",
"apiVersion",
"requestUrls",
"licenseUrl",
"policyUrl",
"rowVersions",
"accessedAt"
],
"properties": {
"source": {
"type": "string",
"const": "CPIC Database",
"description": "Source database."
},
"policyUrl": {
"type": "string",
"description": "ClinPGx usage policy URL."
},
"accessedAt": {
"type": "string",
"description": "UTC access timestamp for live requests."
},
"apiVersion": {
"type": "string",
"const": "v1",
"description": "API interface version, not a database release."
},
"licenseUrl": {
"type": "string",
"description": "Source licence URL."
},
"requestUrls": {
"type": "array",
"items": {
"type": "string"
},
"description": "Exact requests made during this workflow."
},
"rowVersions": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"requestIndex",
"version"
],
"properties": {
"path": {
"type": "string",
"description": "RFC 6901 JSON Pointer to the returned version-bearing record."
},
"version": {
"type": "number",
"description": "Source row version."
},
"requestIndex": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Index in requestUrls of the source request."
}
},
"description": "Version of one retrieved source record.",
"additionalProperties": false
},
"description": "Available source record versions."
},
"primarySourceUrl": {
"type": "string",
"const": "https://www.clinpgx.org/",
"description": "Primary clinical source."
}
},
"description": "Live source attribution and retrieval details.",
"additionalProperties": false
},
"effectiveQuery": {
"type": "object",
"required": [
"geneSymbol",
"diplotype"
],
"properties": {
"diplotype": {
"type": "string",
"description": "Trimmed supplied notation; source responses are unchanged."
},
"geneSymbol": {
"type": "string",
"description": "Normalized exact gene symbol."
}
},
"description": "Effective diplotype query.",
"additionalProperties": false
},
"inputDiplotype": {
"type": "string",
"description": "Trimmed caller notation."
},
"matchedDiplotype": {
"type": [
"string",
"null"
],
"description": "Notation matched in the source, or null."
}
},
"additionalProperties": false
}pgx_lookup_diplotype annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}pgx_get_recommendations — Get recommendations
Advertised read-onlyOpen-world
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.
pgx_get_recommendations input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"mode"
],
"properties": {
"mode": {
"enum": [
"drug",
"genotype",
"results"
],
"type": "string",
"description": "drug requires one drugName or drugId; genotype requires genotype; results requires geneResults or geneSymbol with phenotype/activityScore. Genotype/results optionally accept one drug selector."
},
"view": {
"enum": [
"recommendations",
"test_alerts"
],
"type": "string",
"description": "Select source recommendations (default) or example CDS test alerts with the same selectors and independent paging."
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Positive safe-integer recommendation limit; values above 50 are clamped to 50 with a notice (default 10)."
},
"drugId": {
"type": "string",
"maxLength": 200,
"description": "Exact drugId returned by pgx_search_pairs; blank means unset."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based offset; use nextOffset to continue (default 0)."
},
"drugName": {
"type": "string",
"maxLength": 200,
"description": "Exact case-insensitive drug name; obtain names with pgx_search_pairs. Blank means unset."
},
"genotype": {
"type": "object",
"description": "Required in genotype mode: 1–10 explicit gene/diplotype entries. Every entry must resolve uniquely before lookup.",
"propertyNames": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Gene symbol, normalized to uppercase."
},
"additionalProperties": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "Source-supported diplotype or named allele-status notation."
}
},
"phenotype": {
"type": "string",
"maxLength": 500,
"description": "Source phenotype for geneSymbol; inspect pgx_list_reference topic phenotypes. Excludes activityScore and geneResults."
},
"geneSymbol": {
"type": "string",
"maxLength": 100,
"description": "Gene for a scalar result or exploratory gene filter. Required for a scalar result when the drug has multiple genes."
},
"population": {
"type": "string",
"maxLength": 200,
"description": "Exact source population after outer whitespace trimming; all matching rows are retained."
},
"geneResults": {
"type": "object",
"description": "Explicit results for 1–10 genes; excludes scalar geneSymbol, phenotype, activityScore and genotype.",
"propertyNames": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Gene symbol, normalized to uppercase."
},
"additionalProperties": {
"oneOf": [
{
"type": "object",
"required": [
"kind",
"value"
],
"properties": {
"kind": {
"type": "string",
"const": "phenotype",
"description": "Match the source phenotype, retaining every matching score."
},
"value": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "Exact source result or activity-score string; outer whitespace is ignored."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"kind",
"value"
],
"properties": {
"kind": {
"type": "string",
"const": "activityScore",
"description": "Match a source activity score by exact decimal equivalence."
},
"value": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "Exact source result or activity-score string; outer whitespace is ignored."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"kind",
"value"
],
"properties": {
"kind": {
"type": "string",
"const": "alleleStatus",
"description": "Match one named allele status, including its allele identity."
},
"value": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "Exact source result or activity-score string; outer whitespace is ignored."
}
},
"additionalProperties": false
}
],
"description": "Source gene semantics determine allowed kinds: PHENOTYPE permits phenotype; ACTIVITY_SCORE permits phenotype or activityScore; ALLELE_STATUS permits alleleStatus. Kinds are never converted."
}
},
"activityScore": {
"anyOf": [
{
"type": "string",
"maxLength": 500,
"description": "Exact source decimal or nonnumeric score label; blank means unset."
},
{
"type": "number",
"description": "A supplied numeric source score; no score is calculated."
}
],
"description": "Source activity score for geneSymbol; excludes phenotype and geneResults."
},
"incompleteLimit": {
"type": "integer",
"default": 25,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Positive safe-integer incomplete diagnostic limit; values above 100 are clamped to 100 with a notice (default 25)."
},
"incompleteOffset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Independent zero-based incomplete diagnostic offset; follow incompletePage.nextOffset."
}
},
"additionalProperties": false
}pgx_get_recommendations output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"status",
"items",
"incompleteMatches",
"geneResolutions",
"page",
"incompletePage",
"clinicalCaveat",
"provenance",
"effectiveQuery",
"notices",
"truncated",
"shown",
"cap"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Effective public page limit."
},
"page": {
"type": "object",
"required": [
"limit",
"offset",
"returned",
"total",
"nextOffset"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Effective requested page size."
},
"total": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Exact filtered source count, or null when unavailable."
},
"offset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Requested zero-based offset."
},
"returned": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of rows returned on this page."
},
"nextOffset": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Offset for the next page, or null when no rows remain."
}
},
"description": "Source pagination metadata.",
"additionalProperties": false
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_selector",
"gene_required",
"ambiguous_drug",
"unsupported_gene_result",
"query_too_broad",
"upstream_query_rejected",
"upstream_rate_limited",
"upstream_unavailable"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_selector`: Selectors are missing, conflicting, blank or mixed between modes. `gene_required`: A scalar result cannot identify a unique gene. `ambiguous_drug`: An exact drug name identifies several drug records. `unsupported_gene_result`: A supplied result kind is incompatible with source gene semantics, or its value is unsupported or ambiguous. `query_too_broad`: An internal bounded scan or attempt budget is exceeded. `upstream_query_rejected`: CPIC rejects the generated query. `upstream_rate_limited`: CPIC rate limits requests. `upstream_unavailable`: The source is unavailable or returns maintenance HTML. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer",
"description": "Source record identifier."
},
"drug": {
"anyOf": [
{
"type": "object",
"required": [
"drugid",
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Original source name."
},
"atcid": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Source text list in original order; nullable or absent."
},
"drugid": {
"type": "string",
"description": "Exact source drug identifier."
},
"umlscui": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"version": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Source integer; nullable or absent."
},
"rxnormid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"clinpgxid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"flowchart": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"drugbankid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"guidelineid": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Source integer; nullable or absent."
}
},
"description": "Source drug record.",
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Full embedded source drug, null, or omitted."
},
"drugid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"version": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Source integer; nullable or absent."
},
"comments": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"guideline": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "integer",
"description": "Source record identifier."
},
"url": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"name": {
"type": "string",
"description": "Original source name."
},
"genes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Source text list in original order; nullable or absent."
},
"version": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Source integer; nullable or absent."
},
"clinpgxid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"notesonusage": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
}
},
"description": "Source guideline record.",
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Full embedded source guideline, null, or omitted."
},
"lookupkey": {
"anyOf": [
{
"type": "object",
"description": "Source gene symbols mapped to exact source strings.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Gene-to-required-key map: phenotype, activity score, or allele status according to gene lookup method."
},
"phenotypes": {
"anyOf": [
{
"type": "object",
"description": "Source gene symbols mapped to exact source strings.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Gene-to-phenotype map to which this recommendation applies."
},
"population": {
"type": [
"string",
"null"
],
"description": "Population to which the source recommendation applies."
},
"guidelineid": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Source integer; nullable or absent."
},
"allelestatus": {
"anyOf": [
{
"type": "object",
"description": "Source gene symbols mapped to exact source strings.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Gene-to-allele-presence status map, mainly HLA; missing is never negative."
},
"implications": {
"anyOf": [
{
"type": "object",
"description": "Source gene symbols mapped to exact source strings.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Exact source gene-value map, including empty maps, null, or omitted."
},
"activityscore": {
"anyOf": [
{
"type": "object",
"description": "Source gene symbols mapped to exact source strings.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Gene-to-activity-score string map to which this recommendation applies."
},
"classification": {
"type": [
"string",
"null"
],
"description": "Source recommendation classification, as defined by its guideline supplement."
},
"dosinginformation": {
"type": [
"boolean",
"null"
],
"description": "Source flag; nullable or absent."
},
"drugrecommendation": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"alternatedrugavailable": {
"type": [
"boolean",
"null"
],
"description": "Source flag; nullable or absent."
},
"otherprescribingguidance": {
"type": [
"boolean",
"null"
],
"description": "Source flag; nullable or absent."
}
},
"description": "Source recommendation with guideline and drug records.",
"additionalProperties": {}
},
"description": "Complete source records; matched rows have every required gene result explicitly supplied."
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of returned rows, equal to page.returned."
},
"alerts": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"cdscontext",
"alerttext"
],
"properties": {
"id": {
"type": "integer",
"description": "Source record identifier."
},
"genes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Source text list in original order; nullable or absent."
},
"drugid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"version": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Source integer; nullable or absent."
},
"alerttext": {
"type": "array",
"items": {
"type": "string",
"description": "Exact source alert text."
},
"description": "Complete source alert text in original order, including n/a."
},
"lookupkey": {
"anyOf": [
{
"type": "object",
"description": "Source gene symbols mapped to exact source strings.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Exact source gene-value map, including empty maps, null, or omitted."
},
"phenotype": {
"anyOf": [
{
"type": "object",
"description": "Source gene symbols mapped to exact source strings.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Singular source gene-to-phenotype map."
},
"cdscontext": {
"type": "string",
"description": "Original source CDS context, including No CDS."
},
"population": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"allelestatus": {
"anyOf": [
{
"type": "object",
"description": "Source gene symbols mapped to exact source strings.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Exact source gene-value map, including empty maps, null, or omitted."
},
"activityscore": {
"anyOf": [
{
"type": "object",
"description": "Source gene symbols mapped to exact source strings.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Exact source gene-value map, including empty maps, null, or omitted."
}
},
"description": "Source example test alert; distinct from prescribing recommendations.",
"additionalProperties": {}
},
"description": "Complete source alerts in test_alerts view only; recommendation items remain empty."
},
"status": {
"enum": [
"exploratory",
"matched",
"no_match",
"incomplete",
"unresolved"
],
"type": "string",
"description": "Exploratory browsing, complete genetic match, no match, missing prerequisites, or unresolved genotype."
},
"notices": {
"type": "array",
"items": {
"type": "string",
"description": "Source or workflow notice."
},
"description": "Notices about this result; empty when none apply."
},
"truncated": {
"type": "boolean",
"description": "Whether more matching rows remain after this page."
},
"provenance": {
"type": "object",
"required": [
"source",
"primarySourceUrl",
"apiVersion",
"requestUrls",
"licenseUrl",
"policyUrl",
"rowVersions",
"accessedAt"
],
"properties": {
"source": {
"type": "string",
"const": "CPIC Database",
"description": "Source database."
},
"policyUrl": {
"type": "string",
"description": "ClinPGx usage policy URL."
},
"accessedAt": {
"type": "string",
"description": "UTC access timestamp for live requests."
},
"apiVersion": {
"type": "string",
"const": "v1",
"description": "API interface version, not a database release."
},
"licenseUrl": {
"type": "string",
"description": "Source licence URL."
},
"requestUrls": {
"type": "array",
"items": {
"type": "string"
},
"description": "Exact requests made during this workflow."
},
"rowVersions": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"requestIndex",
"version"
],
"properties": {
"path": {
"type": "string",
"description": "RFC 6901 JSON Pointer to the returned version-bearing record."
},
"version": {
"type": "number",
"description": "Source row version."
},
"requestIndex": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Index in requestUrls of the source request."
}
},
"description": "Version of one retrieved source record.",
"additionalProperties": false
},
"description": "Available source record versions."
},
"primarySourceUrl": {
"type": "string",
"const": "https://www.clinpgx.org/",
"description": "Primary clinical source."
}
},
"description": "Live source attribution and retrieval details.",
"additionalProperties": false
},
"clinicalCaveat": {
"type": "string",
"description": "Source limitations and required clinical qualification."
},
"effectiveQuery": {
"type": "object",
"required": [
"mode",
"limit",
"offset",
"incompleteLimit",
"incompleteOffset"
],
"properties": {
"mode": {
"enum": [
"drug",
"genotype",
"results"
],
"type": "string",
"description": "drug requires one drugName or drugId; genotype requires genotype; results requires geneResults or geneSymbol with phenotype/activityScore. Genotype/results optionally accept one drug selector."
},
"view": {
"enum": [
"recommendations",
"test_alerts"
],
"type": "string",
"description": "Select source recommendations (default) or example CDS test alerts with the same selectors and independent paging."
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Positive safe-integer recommendation limit; values above 50 are clamped to 50 with a notice (default 10)."
},
"drugId": {
"type": "string",
"maxLength": 200,
"description": "Exact drugId returned by pgx_search_pairs; blank means unset."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based offset; use nextOffset to continue (default 0)."
},
"drugName": {
"type": "string",
"maxLength": 200,
"description": "Exact case-insensitive drug name; obtain names with pgx_search_pairs. Blank means unset."
},
"genotype": {
"type": "object",
"description": "Required in genotype mode: 1–10 explicit gene/diplotype entries. Every entry must resolve uniquely before lookup.",
"propertyNames": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Gene symbol, normalized to uppercase."
},
"additionalProperties": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "Source-supported diplotype or named allele-status notation."
}
},
"phenotype": {
"type": "string",
"maxLength": 500,
"description": "Source phenotype for geneSymbol; inspect pgx_list_reference topic phenotypes. Excludes activityScore and geneResults."
},
"geneSymbol": {
"type": "string",
"maxLength": 100,
"description": "Gene for a scalar result or exploratory gene filter. Required for a scalar result when the drug has multiple genes."
},
"population": {
"type": "string",
"maxLength": 200,
"description": "Exact source population after outer whitespace trimming; all matching rows are retained."
},
"geneResults": {
"type": "object",
"description": "Explicit results for 1–10 genes; excludes scalar geneSymbol, phenotype, activityScore and genotype.",
"propertyNames": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Gene symbol, normalized to uppercase."
},
"additionalProperties": {
"oneOf": [
{
"type": "object",
"required": [
"kind",
"value"
],
"properties": {
"kind": {
"type": "string",
"const": "phenotype",
"description": "Match the source phenotype, retaining every matching score."
},
"value": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "Exact source result or activity-score string; outer whitespace is ignored."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"kind",
"value"
],
"properties": {
"kind": {
"type": "string",
"const": "activityScore",
"description": "Match a source activity score by exact decimal equivalence."
},
"value": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "Exact source result or activity-score string; outer whitespace is ignored."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"kind",
"value"
],
"properties": {
"kind": {
"type": "string",
"const": "alleleStatus",
"description": "Match one named allele status, including its allele identity."
},
"value": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "Exact source result or activity-score string; outer whitespace is ignored."
}
},
"additionalProperties": false
}
],
"description": "Source gene semantics determine allowed kinds: PHENOTYPE permits phenotype; ACTIVITY_SCORE permits phenotype or activityScore; ALLELE_STATUS permits alleleStatus. Kinds are never converted."
}
},
"activityScore": {
"anyOf": [
{
"type": "string",
"maxLength": 500,
"description": "Exact source decimal or nonnumeric score label; blank means unset."
},
{
"type": "number",
"description": "A supplied numeric source score; no score is calculated."
}
],
"description": "Source activity score for geneSymbol; excludes phenotype and geneResults."
},
"incompleteLimit": {
"type": "integer",
"default": 25,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Positive safe-integer incomplete diagnostic limit; values above 100 are clamped to 100 with a notice (default 25)."
},
"incompleteOffset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Independent zero-based incomplete diagnostic offset; follow incompletePage.nextOffset."
}
},
"description": "Normalized selectors and effective page defaults.",
"additionalProperties": false
},
"incompletePage": {
"type": "object",
"required": [
"limit",
"offset",
"returned",
"total",
"nextOffset"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Effective requested page size."
},
"total": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Exact filtered source count, or null when unavailable."
},
"offset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Requested zero-based offset."
},
"returned": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of rows returned on this page."
},
"nextOffset": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Offset for the next page, or null when no rows remain."
}
},
"description": "Independent page of incomplete prerequisite diagnostics; totals computed before either page.",
"additionalProperties": false
},
"geneResolutions": {
"type": "array",
"items": {
"type": "object",
"required": [
"found",
"geneSymbol",
"inputDiplotype",
"matchedDiplotype",
"records",
"guidance"
],
"properties": {
"found": {
"type": "boolean",
"description": "Whether source diplotype rows were found."
},
"records": {
"type": "array",
"items": {
"type": "object",
"required": [
"genesymbol",
"diplotype"
],
"properties": {
"diplotype": {
"type": "string",
"description": "Exact source diplotype or allele-status notation."
},
"function1": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"function2": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"lookupkey": {
"anyOf": [
{
"type": "object",
"description": "Source gene symbols mapped to exact source strings.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Normalized source gene result key for recommendation or test-alert lookup."
},
"generesult": {
"type": [
"string",
"null"
],
"description": "Gene phenotype or allele-status result according to the gene lookup method."
},
"genesymbol": {
"type": "string",
"description": "Source HGNC gene symbol."
},
"description": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"ehrpriority": {
"type": [
"string",
"null"
],
"description": "Source EHR Priority Result; not an inferred risk score."
},
"diplotypekey": {
"anyOf": [
{
"type": "object",
"description": "Source gene symbols mapped to allele names and copy counts.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "integer"
}
}
},
{
"type": "null"
}
],
"description": "Original source allele-count key, null, or omitted."
},
"activityvalue1": {
"type": [
"string",
"null"
],
"description": "Source activity assignment for allele slot 1."
},
"activityvalue2": {
"type": [
"string",
"null"
],
"description": "Source activity assignment for allele slot 2."
},
"consultationtext": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"totalactivityscore": {
"type": [
"string",
"null"
],
"description": "Source total diplotype activity-score string; never inferred from missing slots."
}
},
"description": "Source diplotype result and lookup keys.",
"additionalProperties": {}
},
"description": "Every source match; more than one remains ambiguous."
},
"guidance": {
"type": "string",
"description": "Recovery guidance for an unresolved or ambiguous genotype."
},
"geneSymbol": {
"type": "string",
"description": "Normalized supplied gene symbol."
},
"inputDiplotype": {
"type": "string",
"description": "Trimmed caller notation."
},
"matchedDiplotype": {
"type": [
"string",
"null"
],
"description": "Source notation that matched, or null."
}
},
"description": "Source resolution of one explicitly supplied genotype.",
"additionalProperties": false
},
"description": "Per-gene genotype diagnostics, including ambiguity and source records."
},
"incompleteAlerts": {
"type": "array",
"items": {
"type": "object",
"required": [
"testAlertId",
"drugId",
"missingGenes"
],
"properties": {
"drugId": {
"type": [
"string",
"null"
],
"description": "Source drug identifier, or null."
},
"testAlertId": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Source test-alert identifier."
},
"missingGenes": {
"type": "array",
"items": {
"type": "string",
"description": "An explicitly required gene."
},
"description": "Missing source prerequisites; alert text is withheld."
}
},
"description": "Unmatched alert requiring additional explicit results.",
"additionalProperties": false
},
"description": "Independently paged incomplete alerts in test_alerts view only."
},
"incompleteMatches": {
"type": "array",
"items": {
"type": "object",
"required": [
"recommendationId",
"drugId",
"missingGenes"
],
"properties": {
"drugId": {
"type": [
"string",
"null"
],
"description": "Source drug identifier, or null."
},
"missingGenes": {
"type": "array",
"items": {
"type": "string",
"description": "An explicitly required gene."
},
"description": "Missing gene results; no default result is assumed."
},
"recommendationId": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Source recommendation identifier."
}
},
"description": "Recommendation requiring additional explicit gene results.",
"additionalProperties": false
},
"description": "Reference possibilities requiring additional results; never matched prescribing advice."
}
},
"additionalProperties": false
}pgx_get_recommendations annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}pgx_search_alleles — Search alleles
Advertised read-onlyOpen-world
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.
pgx_search_alleles input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"geneSymbol"
],
"properties": {
"name": {
"type": "string",
"maxLength": 500,
"description": "Exact source allele name; blank means unset."
},
"limit": {
"type": "integer",
"default": 25,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Positive safe-integer row limit; values above 100 are clamped to 100 with a notice (default 25)."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based offset; use nextOffset to continue (default 0)."
},
"geneSymbol": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Gene symbol, such as CYP2C19 or HLA-B; outer whitespace is ignored."
},
"clinicalFunctionalStatus": {
"type": "string",
"maxLength": 100,
"description": "Case-insensitive literal source clinical functional status; blank means unset."
}
},
"additionalProperties": false
}pgx_search_alleles output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"oversizedRow",
"items",
"page",
"provenance",
"effectiveQuery",
"notices",
"truncated",
"shown",
"cap"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Effective public page limit."
},
"page": {
"type": "object",
"required": [
"limit",
"offset",
"returned",
"total",
"nextOffset"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Effective requested page size."
},
"total": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Exact filtered source count, or null when unavailable."
},
"offset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Requested zero-based offset."
},
"returned": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of rows returned on this page."
},
"nextOffset": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Offset for the next page, or null when no rows remain."
}
},
"description": "Source pagination metadata.",
"additionalProperties": false
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_selector",
"query_too_broad",
"upstream_query_rejected",
"upstream_rate_limited",
"upstream_unavailable"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_selector`: A required selector is blank after normalization. `query_too_broad`: An internal bounded scan or attempt budget is exceeded. `upstream_query_rejected`: CPIC rejects the generated query. `upstream_rate_limited`: CPIC rate limits requests. `upstream_unavailable`: The source is unavailable or returns maintenance HTML. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"genesymbol",
"name",
"definitionid",
"populationFrequencies"
],
"properties": {
"id": {
"type": "integer",
"description": "Source record identifier."
},
"name": {
"type": "string",
"description": "Original source name."
},
"version": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Source integer; nullable or absent."
},
"findings": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"strength": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"citations": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Source text list in original order; nullable or absent."
},
"frequency": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"number",
"null"
]
}
},
{
"type": "null"
}
],
"description": "Source population-to-frequency fractions, null, or omitted."
},
"genesymbol": {
"type": "string",
"description": "Source HGNC gene symbol."
},
"definitionid": {
"type": "integer",
"description": "Source record identifier."
},
"activityvalue": {
"type": [
"string",
"null"
],
"description": "Source allele activity-score descriptor; distinct from total diplotype activity score."
},
"functionalstatus": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"functioncomments": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"allele_definition": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"genesymbol",
"name"
],
"properties": {
"id": {
"type": "integer",
"description": "Source record identifier."
},
"name": {
"type": "string",
"description": "Original source name."
},
"version": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Source integer; nullable or absent."
},
"genesymbol": {
"type": "string",
"description": "Source HGNC gene symbol."
},
"pharmvarid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"structuralvariation": {
"type": [
"boolean",
"null"
],
"description": "Source flag; nullable or absent."
},
"matchesreferencesequence": {
"type": [
"boolean",
"null"
],
"description": "Source flag; nullable or absent."
}
},
"description": "Source allele definition metadata.",
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Full source allele definition, null, or omitted."
},
"inferredfrequency": {
"type": [
"boolean",
"null"
],
"description": "Source flag; nullable or absent."
},
"populationFrequencies": {
"type": "array",
"items": {
"type": "object",
"required": [
"genesymbol",
"name",
"population_group"
],
"properties": {
"name": {
"type": "string",
"description": "Original source name."
},
"freq_avg": {
"type": [
"number",
"null"
],
"description": "Source frequency fraction, null, or omitted; never an inferred zero."
},
"freq_max": {
"type": [
"number",
"null"
],
"description": "Source frequency fraction, null, or omitted; never an inferred zero."
},
"freq_min": {
"type": [
"number",
"null"
],
"description": "Source frequency fraction, null, or omitted; never an inferred zero."
},
"genesymbol": {
"type": "string",
"description": "Source HGNC gene symbol."
},
"subjectcount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Source integer; nullable or absent."
},
"population_group": {
"type": "string",
"description": "Source population grouping."
},
"freq_weighted_avg": {
"type": [
"number",
"null"
],
"description": "Source frequency fraction, null, or omitted; never an inferred zero."
}
},
"description": "Source population-frequency measurements.",
"additionalProperties": {}
},
"description": "Complete matching population-frequency rows; empty when unavailable."
},
"clinicalfunctionalstatus": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"clinicalfunctionalsubstrate": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
}
},
"description": "Source allele with population-frequency evidence.",
"additionalProperties": {}
},
"description": "Source alleles, embedded definitions and population frequencies."
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of returned rows, equal to page.returned."
},
"notices": {
"type": "array",
"items": {
"type": "string",
"description": "Source or workflow notice."
},
"description": "Notices about this result; empty when none apply."
},
"truncated": {
"type": "boolean",
"description": "Whether more matching rows remain after this page."
},
"provenance": {
"type": "object",
"required": [
"source",
"primarySourceUrl",
"apiVersion",
"requestUrls",
"licenseUrl",
"policyUrl",
"rowVersions",
"accessedAt"
],
"properties": {
"source": {
"type": "string",
"const": "CPIC Database",
"description": "Source database."
},
"policyUrl": {
"type": "string",
"description": "ClinPGx usage policy URL."
},
"accessedAt": {
"type": "string",
"description": "UTC access timestamp for live requests."
},
"apiVersion": {
"type": "string",
"const": "v1",
"description": "API interface version, not a database release."
},
"licenseUrl": {
"type": "string",
"description": "Source licence URL."
},
"requestUrls": {
"type": "array",
"items": {
"type": "string"
},
"description": "Exact requests made during this workflow."
},
"rowVersions": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"requestIndex",
"version"
],
"properties": {
"path": {
"type": "string",
"description": "RFC 6901 JSON Pointer to the returned version-bearing record."
},
"version": {
"type": "number",
"description": "Source row version."
},
"requestIndex": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Index in requestUrls of the source request."
}
},
"description": "Version of one retrieved source record.",
"additionalProperties": false
},
"description": "Available source record versions."
},
"primarySourceUrl": {
"type": "string",
"const": "https://www.clinpgx.org/",
"description": "Primary clinical source."
}
},
"description": "Live source attribution and retrieval details.",
"additionalProperties": false
},
"oversizedRow": {
"type": "boolean",
"description": "Whether one complete indivisible row exceeds the soft byte budget."
},
"effectiveQuery": {
"type": "object",
"required": [
"geneSymbol",
"limit",
"offset"
],
"properties": {
"name": {
"type": "string",
"description": "Effective literal allele name after any supported gene-prefix fallback."
},
"limit": {
"type": "integer",
"default": 25,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Positive safe-integer row limit; values above 100 are clamped to 100 with a notice (default 25)."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based offset; use nextOffset to continue (default 0)."
},
"geneSymbol": {
"type": "string",
"description": "Normalized exact gene symbol."
},
"clinicalFunctionalStatus": {
"type": "string",
"description": "Trimmed case-insensitive literal clinical functional status."
}
},
"description": "Effective allele selectors and page bounds.",
"additionalProperties": false
}
},
"additionalProperties": false
}pgx_search_alleles annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}pgx_list_reference — List pharmacogenomics reference values
Advertised read-onlyOpen-world
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.
pgx_list_reference input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"topic"
],
"properties": {
"limit": {
"type": "integer",
"default": 25,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Positive safe-integer row limit; values above 100 are clamped to 100 with a notice (default 25)."
},
"topic": {
"enum": [
"genes",
"phenotypes",
"cpic_levels",
"pgx_testing",
"classifications",
"input_formats"
],
"type": "string",
"description": "genes lists source gene records; phenotypes requires geneSymbol and lists full gene-result rows; other topics return verified static vocabulary."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based offset; use nextOffset to continue (default 0)."
},
"geneSymbol": {
"type": "string",
"maxLength": 100,
"description": "Exact gene symbol; required for phenotypes, optional for genes, omit for static topics."
}
},
"additionalProperties": false
}pgx_list_reference output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"items",
"page",
"provenance",
"effectiveQuery",
"notices",
"truncated",
"shown",
"cap"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Effective public page limit."
},
"page": {
"type": "object",
"required": [
"limit",
"offset",
"returned",
"total",
"nextOffset"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Effective requested page size."
},
"total": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Exact filtered source count, or null when unavailable."
},
"offset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Requested zero-based offset."
},
"returned": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of rows returned on this page."
},
"nextOffset": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Offset for the next page, or null when no rows remain."
}
},
"description": "Source pagination metadata.",
"additionalProperties": false
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_selector",
"query_too_broad",
"upstream_query_rejected",
"upstream_rate_limited",
"upstream_unavailable"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_selector`: phenotypes lacks a gene or a static topic receives a gene selector. `query_too_broad`: The workflow work budget is exceeded. `upstream_query_rejected`: CPIC rejects the generated query. `upstream_rate_limited`: CPIC returns HTTP 429. `upstream_unavailable`: CPIC is unavailable or returns a maintenance page. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"items": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"required": [
"symbol"
],
"properties": {
"chr": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"url": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"hgncid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"ncbiid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"symbol": {
"type": "string",
"description": "Source HGNC gene symbol."
},
"version": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Source integer; nullable or absent."
},
"clinpgxid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"ensemblid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"lookupmethod": {
"type": [
"string",
"null"
],
"description": "Gene lookup method: PHENOTYPE, ACTIVITY_SCORE, or ALLELE_STATUS."
},
"genesequenceid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"mrnasequenceid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"functionmethods": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"chromosequenceid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"frequencymethods": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"notesondiplotype": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"proteinsequenceid": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"notesonallelenaming": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
},
"includediplotypefrequencies": {
"type": [
"boolean",
"null"
],
"description": "Source flag; nullable or absent."
},
"includephenotypefrequencies": {
"type": [
"boolean",
"null"
],
"description": "Source flag; nullable or absent."
}
},
"description": "Source gene metadata.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"id",
"genesymbol",
"result"
],
"properties": {
"id": {
"type": "integer",
"description": "Source record identifier."
},
"result": {
"type": "string",
"description": "Exact gene phenotype or allele-status result; Indeterminate remains explicit."
},
"version": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Source integer; nullable or absent."
},
"frequency": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"number",
"null"
]
}
},
{
"type": "null"
}
],
"description": "Source population-to-frequency fractions, null, or omitted."
},
"genesymbol": {
"type": "string",
"description": "Source HGNC gene symbol."
},
"ehrpriority": {
"type": [
"string",
"null"
],
"description": "Source EHR Priority Result; not an inferred risk score."
},
"activityscore": {
"type": [
"string",
"null"
],
"description": "Optional source activity-score string; n/a and numeric strings remain distinct."
},
"consultationtext": {
"type": [
"string",
"null"
],
"description": "Source text; nullable or absent."
}
},
"description": "Source gene result and activity score.",
"additionalProperties": {}
},
{
"type": "object",
"required": [
"value",
"meaning",
"sourceUrl"
],
"properties": {
"value": {
"type": "string",
"description": "Exact source vocabulary label or input format."
},
"meaning": {
"type": "string",
"description": "Meaning or usage guidance."
},
"sourceUrl": {
"type": "string",
"description": "Source vocabulary or interface reference URL."
}
},
"description": "Verified static reference entry.",
"additionalProperties": false
}
],
"description": "Gene, gene result, or static reference entry."
},
"description": "Full live gene/result rows or complete static vocabulary entries."
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of returned rows, equal to page.returned."
},
"notices": {
"type": "array",
"items": {
"type": "string",
"description": "Source or workflow notice."
},
"description": "Notices about this result; empty when none apply."
},
"truncated": {
"type": "boolean",
"description": "Whether more matching rows remain after this page."
},
"provenance": {
"anyOf": [
{
"type": "object",
"required": [
"source",
"primarySourceUrl",
"apiVersion",
"requestUrls",
"licenseUrl",
"policyUrl",
"rowVersions",
"accessedAt"
],
"properties": {
"source": {
"type": "string",
"const": "CPIC Database",
"description": "Source database."
},
"policyUrl": {
"type": "string",
"description": "ClinPGx usage policy URL."
},
"accessedAt": {
"type": "string",
"description": "UTC access timestamp for live requests."
},
"apiVersion": {
"type": "string",
"const": "v1",
"description": "API interface version, not a database release."
},
"licenseUrl": {
"type": "string",
"description": "Source licence URL."
},
"requestUrls": {
"type": "array",
"items": {
"type": "string"
},
"description": "Exact requests made during this workflow."
},
"rowVersions": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"requestIndex",
"version"
],
"properties": {
"path": {
"type": "string",
"description": "RFC 6901 JSON Pointer to the returned version-bearing record."
},
"version": {
"type": "number",
"description": "Source row version."
},
"requestIndex": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Index in requestUrls of the source request."
}
},
"description": "Version of one retrieved source record.",
"additionalProperties": false
},
"description": "Available source record versions."
},
"primarySourceUrl": {
"type": "string",
"const": "https://www.clinpgx.org/",
"description": "Primary clinical source."
}
},
"description": "Live source attribution and retrieval details.",
"additionalProperties": false
},
{
"type": "object",
"required": [
"source",
"primarySourceUrl",
"apiVersion",
"requestUrls",
"licenseUrl",
"policyUrl",
"rowVersions",
"verificationDate"
],
"properties": {
"source": {
"type": "string",
"const": "CPIC Database",
"description": "Source database."
},
"policyUrl": {
"type": "string",
"description": "ClinPGx usage policy URL."
},
"apiVersion": {
"type": "string",
"const": "v1",
"description": "API interface version, not a database release."
},
"licenseUrl": {
"type": "string",
"description": "Source licence URL."
},
"requestUrls": {
"type": "array",
"items": {
"type": "string"
},
"description": "Exact requests made during this workflow."
},
"rowVersions": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"requestIndex",
"version"
],
"properties": {
"path": {
"type": "string",
"description": "RFC 6901 JSON Pointer to the returned version-bearing record."
},
"version": {
"type": "number",
"description": "Source row version."
},
"requestIndex": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Index in requestUrls of the source request."
}
},
"description": "Version of one retrieved source record.",
"additionalProperties": false
},
"description": "Available source record versions."
},
"primarySourceUrl": {
"type": "string",
"const": "https://www.clinpgx.org/",
"description": "Primary clinical source."
},
"verificationDate": {
"type": "string",
"description": "Date static vocabulary was verified."
}
},
"description": "Static vocabulary source attribution.",
"additionalProperties": false
}
],
"description": "Live access provenance or static verification provenance."
},
"effectiveQuery": {
"type": "object",
"required": [
"topic",
"limit",
"offset"
],
"properties": {
"limit": {
"type": "integer",
"default": 25,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Positive safe-integer row limit; values above 100 are clamped to 100 with a notice (default 25)."
},
"topic": {
"enum": [
"genes",
"phenotypes",
"cpic_levels",
"pgx_testing",
"classifications",
"input_formats"
],
"type": "string",
"description": "genes lists source gene records; phenotypes requires geneSymbol and lists full gene-result rows; other topics return verified static vocabulary."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based offset; use nextOffset to continue (default 0)."
},
"geneSymbol": {
"type": "string",
"maxLength": 100,
"description": "Exact gene symbol; required for phenotypes, optional for genes, omit for static topics."
}
},
"description": "Normalized topic, gene selector and effective paging.",
"additionalProperties": false
}
},
"additionalProperties": false
}pgx_list_reference annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}Prompts
0 advertised
Resources
1 advertised
pharmacogenomics-guidelines-guide
Turn a patient's pharmacogenomic results (star-allele diplotypes, HLA allele statuses, activity scores, phenotypes) into CPIC recommendations with the pgx_* tools, and find every drug a gene result affects. Use when a task gives a lab PGx result, names a gene–drug pair, or asks what CPIC says about a drug for a genotype.
pharmacogenomics-guidelines-guide URI
skill://pharmacogenomics-guidelines-guide/SKILL.mdio.modelcontextprotocol/skills
io.modelcontextprotocol/skills URI template
skill://{+path}30-day availability
Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.
- Successful checks
- 1 of 1 (100%)
- Average latency
- 825 ms
- 95th percentile latency
- 825 ms
Maintenance history
Public check and source-refresh events. Editorial and ownership records remain private.
- · probe · passed · 825 ms · metadata changed · 6 tool(s), 1 resource(s), 1 resource template(s), 0 prompt(s)
Connect from your client
Each snippet registers the same endpoint; pick the client you use.
Claude Code
Claude Code configuration
claude mcp add --transport http pharmacogenomics-guidelines-mcp-server https://pharmacogenomics-guidelines.caseyjhand.com/mcpCodex
Codex configuration
codex mcp add pharmacogenomics-guidelines-mcp-server --url https://pharmacogenomics-guidelines.caseyjhand.com/mcpCursor
Cursor configuration
{
"mcpServers": {
"pharmacogenomics-guidelines-mcp-server": {
"url": "https://pharmacogenomics-guidelines.caseyjhand.com/mcp"
}
}
}Cline
Cline configuration
{
"mcpServers": {
"pharmacogenomics-guidelines-mcp-server": {
"type": "streamableHttp",
"url": "https://pharmacogenomics-guidelines.caseyjhand.com/mcp",
"disabled": false
}
}
}VS Code
VS Code configuration
{
"servers": {
"pharmacogenomics-guidelines-mcp-server": {
"type": "http",
"url": "https://pharmacogenomics-guidelines.caseyjhand.com/mcp"
}
}
}Gemini CLI
Gemini CLI configuration
gemini mcp add --transport http pharmacogenomics-guidelines-mcp-server https://pharmacogenomics-guidelines.caseyjhand.com/mcpClaude Desktop
Claude Desktop configuration
{
"mcpServers": {
"pharmacogenomics-guidelines-mcp-server": {
"url": "https://pharmacogenomics-guidelines.caseyjhand.com/mcp"
}
}
}Windsurf
Windsurf configuration
{
"mcpServers": {
"pharmacogenomics-guidelines-mcp-server": {
"serverUrl": "https://pharmacogenomics-guidelines.caseyjhand.com/mcp"
}
}
}Let your agent find its tools
Find servers like pharmacogenomics-guidelines-mcp-server from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.