Programmatic variant evidence

A clinical variant interpretation API for agent workflows

Folklore Clinical Variant Interpretation MCP provides a public machine interface for supported GRCh38 germline variants. It returns typed outcomes and structured evidence so an agent can branch deterministically instead of relying on model memory.

Try the task

Resolve rs80357914, and do not select an allele if the result is ambiguous.

Open public variant search to enter one supported GRCh38 germline SNV or simple indel in HGVS, SPDI, rsID or genomic notation. Single supported public queries are free; this does not mean unrestricted platform access or unlimited requests.

No account, API key or OAuth is required. Connect through https://api.helena.bio/folklore/v1/mcp or follow the connector guide.

Minimal call after connecting an MCP client:

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

See eight requests, tool calls and observed results

Already have a ClinVar, Ensembl or publication record?

Use the exact public HGVS, rsID or verified GRCh38 allele from the record, preserving transcript versions. A gene name, phenotype or paper title alone is not a variant identity. Folklore resolves the supported allele and returns automated classification with available evidence and provenance.

Read submitted ClinVar assertions separately from the automated classification. When publications are requested, use the verified identity for variant literature search; a paper association does not establish pathogenicity. Missing evidence and ambiguous identities remain explicit.

Contract first

The endpoint uses stateless Streamable HTTP. A request contains the fixed GRCh38 assembly and one public variant expression. A response preserves resolved, ambiguous, not_found, invalid_request, unsupported and resolution_unavailable states.

Endpoint: https://api.helena.bio/folklore/v1/mcp
Tool: search_variant_evidence
Transport: Streamable HTTP
Authentication: none
Operations: public and read-only

Copy a complete request

This request uses the stateless 2026-07-28 protocol, including routing headers. The hosted SDK also accepts legacy initialize with 2025-03-26. The same scientific schema applies to both modes.

curl https://api.helena.bio/folklore/v1/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: search_variant_evidence' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_variant_evidence","arguments":{"assembly":"GRCh38","query":"GRCh38:chr17:43124027:ACT:A"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

Read the schema and branch before interpretation

Call tools/list with Mcp-Method: tools/list and the same protocol metadata; inspect the search_variant_evidence outputSchema. In a tools/call response the adapter envelope is result.structuredContent. Check the outer JSON-RPC error first. If the envelope result is null, handle adapter_error.code, message and retryable. Otherwise branch on result.status. Resolved identity with interpretation.status unavailable does not supply a classification.

Resolved projection (abbreviated, not the complete response):
{"result":{"structuredContent":{"result":{"status":"resolved","identity":{"canonical_key":"GRCh38:chr17:43124027:ACT:A"}},"adapter_error":null}}}

Ambiguous projection (query rs80357914; no selected identity):
{"result":{"structuredContent":{"result":{"status":"ambiguous","total_candidate_count":2},"adapter_error":null}}}

Exact scientific statuses:
resolved | ambiguous | not_found | invalid_request | unsupported | resolution_unavailable

Compose evidence and literature

After a variant resolves, reuse its canonical key with search_variant_literature. Retrieve a returned PMID with get_publication_details, or use search_literature_corpus for a broader source-linked literature question. Publication association remains distinct from pathogenicity and causality.

Public scientific boundary

Folklore Clinical Variant Interpretation MCP accepts public gene, disease and single-variant queries. Do not send patient, phenotype, family, segregation or private case data. Results are automated decision support for qualified professional review, not a diagnosis or treatment recommendation.

Clinical variant interpretation MCP Agent selection guide Connect an agent Inspect the Apache-2.0 adapter Review limitations

Using Folklore with your laboratory or research team?

Introduce your team if you would like help connecting your agents or a conversation about working together.

Introduce your team

Optional. Public variant interpretation remains available without an introduction.