Folklore MCP

Connect your client

Add the endpoint to your AI client as a remote MCP server using Streamable HTTP.

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

Codex configuration:

[mcp_servers.folklore]
url = "https://api.helena.bio/folklore/v1/mcp"

Cursor configuration:

{
  "mcpServers": {
    "folklore": {
      "url": "https://api.helena.bio/folklore/v1/mcp"
    }
  }
}

For case workflows, create an API key in Account > API keys for your selected Personal or Workspace account. Store the key in your client's secret settings and configure this header. No local Folklore server is required.

Authorization: Bearer <your Folklore API key>

The anonymous catalog has 11 tools; current admitted credentials expose 29. Subscription capabilities, usage limits and eligible credits apply to case processing.

Tools

Public tools. No account or API key is required for these 11 scientific queries and support lookup.

Supported variant queries include GRCh38 coordinates, selected HGVS forms, SPDI and rsID for nuclear germline SNVs and simple indels smaller than 50 base pairs. For ambiguous expressions, review the returned candidates and verify the intended allele.

API-key tools

Select a context and source, then submit with an explicit cost ceiling and original idempotency key. Poll the accepted analysis, read its manifest and query the selected frozen JSON export. An original download returns a protected API URL; fetch it with the same Bearer credential.

Example questions

Which genes have curated evidence for Marfan syndrome?

Which diseases are associated with FBN1?

Classify ENST00000226413.5:c.317A>G under ACMG/AMP
and summarize its supporting evidence.

For a gene profile, first call resolve_gene. BRCA1 resolves to candidate identity.gene_id HGNC:1100. Pass the returned identity_snapshot_id as snapshot_id in subsequent calls; select a candidate explicitly when ambiguous and preserve withdrawn or not_found outcomes.

tools/call params (replace <identity_snapshot_id> with the value returned by resolve_gene):
{"name":"resolve_gene","arguments":{"query":"BRCA1"}}
{"name":"get_gene_profile","arguments":{"gene_id":"HGNC:1100","snapshot_id":"<identity_snapshot_id>"}}
{"name":"get_gene_section","arguments":{"gene_id":"HGNC:1100","snapshot_id":"<identity_snapshot_id>","section":"structure","limit":20}}
{"name":"search_gene_literature","arguments":{"gene_id":"HGNC:1100","snapshot_id":"<identity_snapshot_id>","limit":20,"sort":"relevance"}}

Continue sections with the returned next_cursor and the same gene, snapshot and section; limit is 1 to 50. Literature uses a separate live capture, limit 1 to 25 and relevance, newest or oldest sort; preserve its capture time/hash and keep the same sort for pagination. Restart resolution after snapshot_unavailable.

Read the evidence

Keep the resolved allele, classification, criterion evidence, source citations and limitations together. Keep gene source provenance, coverage, count units, total versus observed_total and unavailable states intact. Gene-disease validity, constraint and GWAS records retain their source assessments. Live gene literature excludes abstracts and is separate from the immutable profile literature section.

Anonymous inputs are public gene/disease identifiers, variant expressions and scientific literature queries. Authenticated tools use the selected account's admitted case, source and artifact identities.

Client setup and resources

Public integration repository · MCP server card · Directory listings