Folklore Variant Evidence

Use Folklore Clinical Variant Interpretation MCP to retrieve structured public

variant evidence, automated variant-level ACMG/AMP decision support, provenance,

and source-linked literature for professional review. Keep the workflow limited

to public identifiers and preserve every explicit outcome state. Adapter 1.5.0 also provides ClinGen Gene-Disease Validity assertions; source coverage is bounded, not every known association.

Folklore Clinical Variant Interpretation MCP is published by Helena

Bioinformatics. Its hosted endpoint is:

https://api.helena.bio/folklore/v1/mcp

No account or API key is required. The public Apache-2.0 adapter and contract are

available at <https://github.com/helena-bioinformatics/folklore-mcp>.

Minimal connection example

A host without native MCP support can make the same public JSON-RPC call:

curl --silent --show-error --fail-with-body --max-time 60 \
  -X POST https://api.helena.bio/folklore/v1/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: search_variant_evidence' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}},"name":"search_variant_evidence","arguments":{"assembly":"GRCh38","query":"rs80357914"}}}'

The routing headers must match the JSON-RPC method and tool name. A successful

HTTP response is not sufficient: inspect JSON-RPC error, then

result.structuredContent.adapter_error, then this tool's

result.structuredContent.result.status. Other tools use different response

shapes; use the [contract table](references/mcp-contract.md).

Inspect the returned outcome before continuing. This example can return

ambiguous with multiple candidates: stop and request an unambiguous public

variant notation instead of selecting a candidate automatically.

Select the right skill

Use this skill when the task is one public variant to structured Folklore

evidence, explicit resolution-state handling, variant-linked literature, or ClinGen gene-to-disease/disease-to-gene assertions.

• Use database-lookup for broad direct queries across ClinVar, dbSNP, gnomAD,

Ensembl VEP, COSMIC, or multiple databases.

• Use genomic-coordinates first when the assembly, coordinate convention,

contig name, or variant representation is uncertain.

• Do not use this skill for VCF annotation, batch processing, somatic variants,

structural variants, polygenic scores, or patient-specific interpretation.

Folklore Clinical Variant Interpretation MCP complements those skills with one

source-linked public evidence contract. It does not replace direct database

review or qualified clinical judgment.

Enforce the input boundary

Before a variant tool call:

1. Extract exactly one public variant identifier or notation.
2. Require GRCh38 and a germline nuclear SNV or simple insertion/deletion shorter

than 50 base pairs. An unsupported assembly may be rejected by the input

schema before any scientific unsupported status exists.

1. Remove or refuse patient names, case identifiers, phenotypes, family history,

segregation evidence, clinical records, uploaded files, and other private or

patient-specific context.

1. If the task depends on patient context, stop and explain that Folklore

Clinical Variant Interpretation MCP does not accept or evaluate it.

1. Never transform a patient-specific request into a public variant query while

implying that the result answers the patient-specific question.

Accepted public variant forms include genomic coordinates, genomic/coding/

protein HGVS, SPDI, rsID, or a canonical_key returned by Folklore Clinical

Variant Interpretation MCP.

Verify the live tool catalog

Connect to the hosted endpoint and call tools/list. Verify the available tools

instead of relying on model memory. The documented public catalog contains:

• search_variant_evidence
• search_variant_literature
• get_publication_details
• search_literature_corpus
• get_gene_disease_associations
• search_disease_genes

The separate seventh tool support_helena is not scientific evidence; use it only when explicitly requested.

If discovery or a tool call fails, preserve the failure as an availability

problem. Do not reinterpret it as lack of scientific evidence.

Read [the public MCP contract](references/mcp-contract.md) before composing tool

calls or interpreting response states.

Retrieve gene-disease assertions

Use get_gene_disease_associations for one exact gene symbol or HGNC identifier, or search_disease_genes for an exact MONDO identifier or public disease-name substring. Both accept limit (default 20, 1–50) and offset (default 0, 0–1000). See the reference for request examples. This is a separate source lookup and requires no variant input or assembly.

Preserve each returned disease identity, inheritance, evidence assessment, source

URL, date, source.version and source.snapshotSha256. This is a local ClinGen

snapshot, not a guarantee of the latest ClinGen release. Follow

pagination.nextOffset while it is present; preserve pagination-ceiling warnings.

An empty page after the total has been passed does not mean the initial query had

no matches. Do not combine distinct diseases or silently choose among name matches.

Gene-disease validity does not classify a particular variant. A not_found

response means no matching assertion in the available source, not no association.

No patient, phenotype, family, segregation, private case data or sequencing files

may be sent. Qualified professional review remains required.

Run the variant-evidence workflow

1. Resolve and retrieve evidence

Call search_variant_evidence with:

assembly: GRCh38
query: <one public variant identifier or notation>

Do not add phenotype, disease, patient, family, or treatment context to this

call. Preserve the returned contract fields, source links, limitations, and

usage boundary.

2. Branch on the returned status

Read transport/JSON-RPC errors and adapter_error first. For

search_variant_evidence, let envelope = result.structuredContent; only if

envelope.result is non-null, branch on envelope.result.status. An

invalid_arguments adapter error is distinct from scientific invalid_request.

Preserve isError and any typed failure, including resolution_unavailable.

Treat the status as a control-flow value, not prose:

Only a resolved result may proceed automatically into a variant-linked

literature workflow. Its canonical key is envelope.result.identity.canonical_key.

If envelope.result.interpretation.status is unavailable, preserve its typed

error; identity resolution has succeeded, but classification has not. Do not read

or invent a classification for that outcome.

3. Review the evidence without overclaiming

For a resolved result:

• Present the returned variant identity and canonical_key.
• Preserve the automated variant-level ACMG/AMP decision-support result exactly

as returned.

• Cite the returned public sources and provenance.
• Keep submitted ClinVar assertions separate from Folklore's automated result,

as required by the upstream interpretation guidance.

If they disagree, report each assertion with its source/date and preserve

the disagreement; do not present a merged consensus classification.

• Separate returned facts from the agent's synthesis.
• State that qualified professional review is required.
• Do not turn the result into a diagnosis, individual risk estimate, treatment

recommendation, or standalone clinical report.

Chain into literature

Variant-linked literature

After a resolved evidence call, pass the returned canonical_key to

search_variant_literature. Keep assembly as GRCh38. An optional question

may narrow the literature focus, but it must remain a public scientific question

and must not contain patient context.

Distinguish each result's match type:

• exact_variant: direct match to the resolved variant
• variant_alias: match through a reported alias
• gene_association: broader gene-level association, not variant-specific proof

Literature associations do not alter the returned ACMG/AMP classification.

Publication details

Call get_publication_details only with a PMID returned by the literature tools.

Preserve PubMed URLs, DOI/PMCID fields when present, retraction status, and the

distinction between gene mentions and variant mentions.

Semantic corpus search

Use search_literature_corpus for a public natural-language scientific question

or for discovery by publication identifier, gene, variant, phenotype, HPO, or

OMIM concept. Treat results as source-linked candidates for professional review.

A zero-result response means no result was returned for that bounded query, not

that no relevant publication exists anywhere.

The query is 3–200 characters, with limit 1–25 and sort set to relevance,

newest, or oldest. For another page, reuse the returned opaque next_cursor

with the same query and sort; do not construct an offset. Keep match_types and

article_entities distinct from variant-literature match types. Report

semantic_index_used and semantic_degraded_reason; a returned lexical match

does not prove semantic retrieval worked. Preserve additional retrieval metadata

returned by the live service.

Do not place patient information into a corpus query, even if the query is not

variant-specific.

Report a reproducible result

Include:

1. The exact public query and GRCh38 assembly.
2. The returned status and, if resolved, the canonical_key.
3. The structured evidence or literature result without changing its meaning.
4. Source links and publication identifiers.
5. Match type for literature results.
6. Access date and any availability limitation.
7. This boundary statement:

This is public, variant-level decision support for qualified professional

review. It does not evaluate patient, phenotype, family, segregation, or

private case data and is not a diagnosis or treatment recommendation.

Falsifiable smoke test

Use the public rsID rs80357914 to test ambiguity handling:

Call search_variant_evidence with assembly GRCh38 and query rs80357914. If the
result is ambiguous, list the returned candidates and stop for explicit
selection. Do not select a candidate or call downstream literature tools.

The ambiguity branch passes only if an ambiguous response causes the workflow to

stop without automatic candidate selection. If the live response changes, record

the actual status; a resolved response does not test ambiguity handling.

On 2026-09-30, live discovery reported adapter 1.5.0 and protocol 2026-07-28.

The rsID example returned ambiguous; a separate public HGVS query resolved and

was chained through its returned key to literature and a returned PMID. Corpus

cursor pagination and gene-disease offset pagination were exercised. These are

dated protocol checks, not validation of clinical accuracy. See the reference

for exact response shapes and source/live differences.

Official references

• Integration setup: <https://folklore.helena.bio/integrations>
• Technical guide: <https://folklore.helena.bio/docs/folklore-connector>
• Public adapter and contract: <https://github.com/helena-bioinformatics/folklore-mcp>
• Official MCP Registry identity: io.github.helena-bioinformatics/folklore