Skip to main content
Glama
Folklore Clinical Variant Interpretation MCP

Folklore Clinical Variant Interpretation MCP

Folklore Clinical Variant Interpretation MCP

One hosted MCP server for public scientific queries and authenticated case workflows.

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

Version 2.0.0

License DOI OpenSSF Scorecard AllMCPs Verified

Connect your MCP client directly to this Streamable HTTP endpoint. No local Folklore server is required. Anonymous callers receive 11 public tools. Send your Folklore API key in the Authorization Bearer header to access 18 additional case, source and result tools at the same endpoint. Invalid supplied credentials fail authentication; they do not select the anonymous catalog.

Create a key in your Folklore account for the selected account and sources. Keep it in your client's secret store, never in prompts, tool arguments or URLs. The selected account's native subscription capabilities, usage limits and eligible credits govern processing. A key does not grant funded compute.

See case workflows, the 18 authenticated tool schemas and the public task recipes.

Classify a variant

Connect your MCP client to:

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

Access is anonymous. Call classify_germline_variant:

{"name":"classify_germline_variant","arguments":{"assembly":"GRCh38","query":"NM_007294.4:c.68_69del"}}

Input: one public GRCh38 nuclear germline SNV or simple indel smaller than 50 bp. Accepted notation includes supported HGVS, SPDI, rsID and genomic coordinates. Preserve transcript versions and reference alleles.

A resolved identity with successful interpretation includes automated ACMG/AMP classification, reported criteria, annotations, source evidence and provenance. Submitted ClinVar assertions retain their own source attribution alongside the Folklore classification. A VUS is a classification outcome.

Status

Next step

resolved

Read interpretation status, then classification and evidence.

ambiguous

Present candidates for an explicit allele choice.

not_found

Report the source-scoped miss.

invalid_request

Supply a corrected supported expression.

unsupported

Select a workflow for the requested variant type or assembly.

resolution_unavailable

Inspect the typed error and retry policy.

Interpretation status is success or unavailable. Transport, JSON-RPC, MCP and adapter errors have separate fields. See typed outcomes.

Related MCP server: allele-registry-mcp-server

Scientific tools

Tool

Operation

classify_germline_variant

Resolve, classify and assess one supported germline variant.

search_variant_literature

Retrieve publications linked to a resolved variant.

get_publication_details

Retrieve the bibliographic record and abstract for a PMID.

search_literature_corpus

Search publications by scientific question or public identifier.

get_gene_disease_associations

Retrieve ClinGen assertions for an exact gene symbol or HGNC identifier.

search_disease_genes

Retrieve ClinGen assertions by MONDO identifier or disease-name substring.

resolve_gene

Resolve a human gene symbol, alias or stable identifier.

get_gene_profile

Read the selected HGNC gene at its returned snapshot.

get_gene_section

Continue one profile section using its cursor.

search_gene_literature

Retrieve a separate live publication capture for the selected gene.

ClinGen results preserve assertion-level disease identity, inheritance, validity assessment, panel, date and source links. Profile sections retain provider, assembly, release, units and pagination. Gene literature has its own capture identity. Follow gene-disease and gene-profile contracts for exact inputs.

support_helena provides links to the separate Helena Good service when the user asks about supporting Helena. An optional MCP App renders variant results.

Connect an agent or application

The hosted server uses stateless Streamable HTTP and MCP 2026-07-28. Requests carry matching protocol metadata and routing headers. Supported methods include server/discover, tools/list, tools/call, prompts/list, prompts/get, resources/list and resources/read.

The compatibility guide records protocol/client observations. All clients sharing egress use the same rate budget.

Agent Skill and workflow prompts

Install the portable Agent Skill using the installation guide. It routes pathogenicity, VUS, ClinVar, population-frequency, gene-disease and literature tasks to the hosted tools. The skill source includes OpenAI interface metadata.

Workflow prompts compose tool operations for classification, VUS assessment, ACMG/AMP explanation, identity verification and variant-literature comparison. Each accepts one public variant expression.

Run the adapter

The Apache-2.0 adapter implements MCP transport, public API clients and validated response projection. Folklore's scientific authorities produce normalization, annotation, evidence aggregation and classification.

python3.12 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
FOLKLORE_MCP_ENABLED=true \
FOLKLORE_LITERATURE_ENABLED=true \
FOLKLORE_GENE_DISEASE_ENABLED=true \
FOLKLORE_PUBLIC_GENE_ENABLED=true \
folklore-mcp

Capabilities are enabled through the flags above. Gene literature requires both public-gene and literature capabilities. The default upstream is https://api.helena.bio; local contract tests support localhost and 127.0.0.1. The standalone HTTP image uses Dockerfile.adapter; Dockerfile provides the pinned stdio bridge.

Verify and measure

pytest
ruff check .
ruff format --check .
python3 ops/reconcile_discovery.py

The read-only reconciler compares runtime, Server Card and Official Registry state, with separate aggregator observations. python3 ops/public_smoke.py checks discovery, prompts and resources.

Public measurement sources: variant interpretation, 100-case agent discovery, 60-query search discovery and genomic discovery cohort.

Registry and citation

The immutable MCP adapter 1.6.0 archive is 10.5281/zenodo.23817704, from signed tag folklore-mcp-v1.6.0 at 55a332c6dd6bd4650e921c12ac145b8e0f90476a. The Biorouter-tag archive is 10.5281/zenodo.23818207.

License

Apache License 2.0. See LICENSE and NOTICE.

Automated variant classifications support qualified professional review and are not patient diagnoses or treatment recommendations.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables resolving genetic variant identifiers (HGVS, dbSNP, ClinVar, gnomAD) to stable ClinGen Allele Registry IDs (CA#) and cross-references, providing a canonical allele identity across genome builds.
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Look up variant allele frequencies by ancestry, gene loss-of-function constraint, gene variant lists, and sequencing coverage over gnomAD — with ClinVar significance joined in — via MCP.
      272 npm
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables searching cancer genes and curated variants from CIViC, retrieving associated diseases, therapies, and graded evidence items and assertions for clinical interpretation.
      58 npm
      MIT