MCP

The same data as tools, for an AI assistant: run the server, connect a client, then look up a tool.

Data release 2026.11. 48 tools, the ones the site's AI Chat uses.

Start here

An MCP server gives an AI assistant the data the API gives a script, as tools it can call and read. The site's own AI Chat calls the same tools.

1

Install and run

The server is the discanvis_mcp package of the DisCanVis repository (Python 3.10 or newer) and needs the mcp package, which is not in the repository's requirements.txt. Run it from the repository root; it speaks MCP over stdio unless told otherwise.

pip install mcp
python -m discanvis_mcp.server
A network server instead of stdio
python -m discanvis_mcp.server --transport streamable-http --host 127.0.0.1 --port 8765
2

Point it at a site

Every tool reads a DisCanVis site over HTTP, at DISCANVIS_BASE_URL. Its default is a local server on port 8001; for the public site set it as below. The other variables are under Settings.

export DISCANVIS_BASE_URL=https://discanvis.elte.hu
3

Connect a client

In any MCP client, add the server. Over stdio the client starts it; over streamable HTTP it connects to the address (the MCP Python SDK serves it at /mcp). The key names differ a little between clients.

stdio
{
  "mcpServers": {
    "discanvis": {
      "command": "python",
      "args": [
        "-m",
        "discanvis_mcp.server"
      ],
      "env": {
        "PYTHONPATH": "/path/to/DisCanVis2",
        "DISCANVIS_BASE_URL": "https://discanvis.elte.hu"
      }
    }
  }
}
streamable-http
{
  "mcpServers": {
    "discanvis": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

There is no hosted MCP endpoint. The server is run on your own machine and reads a DisCanVis site over HTTP: the public site, https://discanvis.elte.hu, or your own deployment. Some tools read page feeds that the API page lists as not documented, so they follow the pages; a few readings need the site's own code and say so (marked on their cards).

How answers look

EnvelopeEvery tool answers with one object: tool, summary, evidence, provenance, caveats, data, error. The fields are below.
ErrorsA failed call is an answer, not an exception: error is {"kind", "message", "details"} and summary says Validation failed or Request failed. The kinds are below. An unknown tool name is the one call that raises.
No score, no callA reading that needs a number the data does not have says so (available: false, —, not recorded), and keeps 'looked up and absent' apart from 'not looked up'. Cutoffs are the published ones, named with the score.
Read-onlyNo tool writes anything. Most tools only read (GET); batch_analyze and the variant readings POST a request to compute an answer.
ContractThe response contract version is v1; the envelope above is what it names.
Request timeout20 · Seconds one request to the site may take (ordinary tools).
Batch timeout120 · Seconds for a proteome-wide batch_analyze scan.
Retries2 · Extra tries after a connection error or a 5xx, 408 or 429 answer.
Retry wait0.4 · Seconds before the first retry; it doubles each time.
Variants per list25 · interpret_variants reads this many changes; the rest are named as skipped.
Top rows per cohort25 · profile_cohort returns this many top rows (it reads up to the Analysis upload limit of 1 000; the rest are counted).
Substitutions compared2 to 6 · compare_substitutions takes two to this many changes at one residue.
Cohort pages5 · Pages of 200 rows the set tools read (the Cancer Gene Census is 857 proteins).
Partners and segments12 · The interface reading names at most this many partners and spans.
Motif classes5 · get_motif_class describes at most this many classes of one name.
PubMed records10 · search_literature returns 1 to 10 records (max_results).
Ranked proteins50 · rank_disorder_burden ranks at most this many (n, 25 by default).
Ranked motif sites25 · rank_motif_instances ranks at most this many (n, 5 by default).
The envelope
FieldHolds
toolThe tool's name.
summaryOne line saying what was done, or Validation failed / Request failed.
evidenceThe compact, decision-ready part: counts, readings and the rows a model needs first.
provenanceWhere the numbers come from: the endpoint, the package, the build.
caveatsWhat the reader must not over-read (a list of sentences).
dataThe full upstream answer, for a consumer that wants the rest.
errornull, or the error object below. When it is set, evidence and data are empty.
Error kinds
error.kindMeans
ambiguous_isoformMore than one isoform fits; name one.
invalid_inputThe arguments were refused before any request.
no_dataThe question was valid and there is nothing recorded.
unresolved_identifierNo protein by that name.
unsupported_annotationThe layer name is not one the site serves.
upstream_errorThe request failed, or the server answered with an error (also any other failure).

Read a protein

One protein at a time: every layer, one layer, the Summary overview, function and Gene Ontology.

tool get_protein_full

The whole annotation bundle of one protein, the same JSON as /rest/{id}.json.

Parameters
NameTypeRequiredDefaultMeaning
identifierstringrequired—The protein: a GENCODE accession (RAF1-201), a gene symbol, a UniProt accession or an Ensembl transcript, as named by search_type.
search_typestringoptional'gencode'What identifier is: gencode (the default), gene_name, uniprot or transcript. A gene with several isoforms answers with its main isoform.
Returns

In data the whole REST payload: the sequence and every annotation layer (about 40: disorder, structure, domains, motifs, PTMs, germline and somatic variants, predictors, conservation, exons). evidence is a compact digest of the mutations against the motifs, placed ahead of the dense per-residue arrays.

Wraps
RequestOn the API page
/rest/{id}.jsonGET /rest/{id}.{format}
What the model is told

Fetch the complete DisCanVis per-protein annotation bundle as raw REST JSON (/rest/{id}.json). Returns sequence plus every annotation layer available for the protein: disorder (IUPred, MobiDB, combined), structure (AlphaFold pLDDT, PDB), Pfam domains, linear motifs, PTM sites, ClinVar / TCGA / COSMIC / cBioPortal mutations, AlphaMissense + dbNSFP pathogenicity, PhasePro/DIBS/MFIB binding regions, conservation, and exon boundaries. Use for one-gene overview questions ('sequence, domains, and annotation layout of EGFR', 'compare TCGA vs ClinVar tracks on PTEN'), and as the first call before drilling into a region or position. Prefer over multiple get_annotation calls when the user wants context across layers. Do NOT use when the user asks for the DisCanVis summary figure/plot — call get_summary_bundle instead. Args: identifier, search_type. search_type is one of 'gene_name' (e.g. 'CTNNB1'), 'uniprot' (e.g. 'P35222'), 'transcript' (Ensembl 'ENST...'), 'gencode' (GENCODE protein accession), or 'ensembl' (Ensembl gene 'ENSG...'). Pick the one that matches the identifier the user gave. Its readout leads with `motifs.layers`: curated ELM and MoMAP instances and predicted PEM and ScanSite sites, each counted, with how many fall in disordered stretches and the first records. Read every layer before saying a protein has no motifs; `count: 0` is checked-and-none, `not read here` is not a finding.

tool get_annotation

One annotation layer of one protein, for example the Pfam domains or the ClinVar records.

Parameters
NameTypeRequiredDefaultMeaning
identifierstringrequired—The protein: a GENCODE accession (RAF1-201), a gene symbol, a UniProt accession or an Ensembl transcript, as named by search_type.
modelstringrequired—The layer name, as in /rest/{id}/{layer}: pfam, clinvar, tcgam, elm, iupred and the other names on the API page's Layer names table.
search_typestringoptional'gencode'What identifier is: gencode (the default), gene_name, uniprot or transcript. A gene with several isoforms answers with its main isoform.
Returns

The rows of that layer with its columns, a short reading of what the layer is (method, whether it is observed or predicted), and for the variant layers the records, unique variants and recurrence counted apart.

Wraps
RequestOn the API page
/rest/{id}/{model}GET /rest/{id}/{layer}
Example call
{
  "identifier": "RAF1-201",
  "model": "pfam"
}
Example result · abridged, RAF1, standalone server
{"tool": "get_annotation",
 "summary": "Fetched annotation model 'pfam' (3 rows)",
 "evidence": {"model": "pfam", "payload_type": "text",
              "source": {"source": "Pfam domains", "evidence": "predicted",
                         "evidence_means": "Placed on the sequence by a method, not observed."},
              "rows": 3,
              "columns": ["Protein ID", "alignment_start", "alignment_end", "hmm_name", "type", …],
              "records": [{"Protein ID": "RAF1-201", "alignment_start": "351", "alignment_end": "605",
                           "hmm_name": "PK_Tyr_Ser-Thr", "type": "Domain", "e_value": "3.1e-63", …},
                          {"alignment_start": "139", "alignment_end": "186", "hmm_name": "C1_1", …},
                          {"alignment_start": "57", "alignment_end": "128", "hmm_name": "RBD", …}]},
 "provenance": {…}, "caveats": [], "data": {…}, "error": null}
What the model is told

Fetch a SINGLE annotation layer for a protein from /rest/{id}/{model}. Use when the user asks about one specific track (e.g. 'ClinVar variants in LMOD3', 'Pfam domains of EGFR', 'PTM sites on TP53'). Prefer get_protein_full when the user wants multiple layers at once. Common model values: 'iupred', 'mobidb', 'alphafold', 'pdb', 'pfam', 'elm', 'elmswitches', 'ptm', 'binding', 'phasepro', 'dibs', 'mfib', 'roi', 'conservation', 'phastcons', 'clinvar', 'pathogenicity', 'omim', 'polymorphism', 'tcgam', 'tcgaf', 'tcgai', 'cosmicm', 'cosmicf', 'cosmici', 'cbioportalm', 'cbioportalf', 'cbioportali', 'anchor', 'aiupred-binding', 'exon'. Args: identifier, model, search_type. search_type is one of 'gene_name' (e.g. 'CTNNB1'), 'uniprot' (e.g. 'P35222'), 'transcript' (Ensembl 'ENST...'), 'gencode' (GENCODE protein accession), or 'ensembl' (Ensembl gene 'ENSG...'). Pick the one that matches the identifier the user gave.

tool get_summary_bundle

The bundle the Summary figure is drawn from.

Parameters
NameTypeRequiredDefaultMeaning
identifierstringrequired—The protein: a GENCODE accession (RAF1-201), a gene symbol, a UniProt accession or an Ensembl transcript, as named by search_type.
search_typestringoptional'gencode'What identifier is: gencode (the default), gene_name, uniprot or transcript. A gene with several isoforms answers with its main isoform.
Returns

Disorder, Pfam, ELM, PTM, ClinVar, AlphaMissense, cancer mutations, PDB and conservation in the shape the Summary page reads. A large answer.

Wraps
RequestOn the API page
/summary/api/bundleThe shape the AI Chat tools read (about 2.4 MB); it follows the figure and is not a stable contract.
What the model is told

Preferred tool when the user asks to SEE the DisCanVis summary figure / plot for a protein. Returns the aggregated Summary-page bundle (disorder, Pfam, ELM, PTM, ClinVar, AlphaMissense, cancer mutations, PDB and conservation) that the /summary/<accession> page consumes; consumers can render the same VisualRenderer figure from it. Use for 'show me the summary of TP53', 'plot CTNNB1', 'visualize FOXP2'. Do NOT use when the caller wants raw per-layer JSON — use get_protein_full for that. Args: identifier, search_type. search_type is one of 'gene_name' (e.g. 'CTNNB1'), 'uniprot' (e.g. 'P35222'), 'transcript' (Ensembl 'ENST...'), 'gencode' (GENCODE protein accession), or 'ensembl' (Ensembl gene 'ENSG...'). Pick the one that matches the identifier the user gave.

tool get_mechanism_overview

The Summary Overview as data: where the mutations of a protein concentrate and what is annotated there.

Parameters
NameTypeRequiredDefaultMeaning
identifierstringrequired—The protein: a GENCODE accession (RAF1-201), a gene symbol, a UniProt accession or an Ensembl transcript, as named by search_type.
search_typestringoptional'gencode'What identifier is: gencode (the default), gene_name, uniprot or transcript. A gene with several isoforms answers with its main isoform.
Returns

The significantly mutated regions, ranked, each with its coordinates, cancer types, observed positions and counts, disorder context and the overlapping motifs, domains, PTMs and structures.

Wraps
RequestOn the API page
/rest/{id}.jsonGET /rest/{id}.{format}
/summary/api/bundleThe shape the AI Chat tools read (about 2.4 MB); it follows the figure and is not a stable contract.
/summary/api/overview/{id}/GET /summary/api/overview/{accession}/
What the model is told

Return the machine-readable version of the Summary Overview for a cancer/mutation mechanism question. It ranks precomputed significantly mutated regions and, for each, returns strict coordinates, significant cancer types, observed mutation positions/counts, disorder context and overlapping ELM/domain/PTM/PDB annotations. Use FIRST for questions such as 'how do CTNNB1 cancer mutations work?', 'where are pathogenic mutations concentrated?', or 'what annotated mechanism overlaps the most mutated regions?'. The returned observed counts are not a new enrichment statistic; the significance label comes only from the stored ROI result. Use get_region afterwards only when a specific top region needs deeper inspection. Args: identifier, search_type. search_type is one of 'gene_name' (e.g. 'CTNNB1'), 'uniprot' (e.g. 'P35222'), 'transcript' (Ensembl 'ENST...'), 'gencode' (GENCODE protein accession), or 'ensembl' (Ensembl gene 'ENSG...'). Pick the one that matches the identifier the user gave.

tool get_functional_context

Curated functional disorder: DisProt, phase separation, disordered binding regions and variant-effect assays.

Parameters
NameTypeRequiredDefaultMeaning
identifierstringrequired—The protein: a GENCODE accession (RAF1-201), a gene symbol, a UniProt accession or an Ensembl transcript, as named by search_type.
search_typestringoptional'gencode'What identifier is: gencode (the default), gene_name, uniprot or transcript. A gene with several isoforms answers with its main isoform.
Returns

DisProt regions, LLPS records, DIBS / MFIB / PhaSePro regions, MaveDB / ProteinGym coverage and UniProt region and binding annotations, with a protein-level reading of the phase-separation spans.

Wraps
RequestOn the API page
/rest/{id}.jsonGET /rest/{id}.{format}
/summary/DibsMfibA page feed that is not on the API page.
/summary/MaveA page feed that is not on the API page.
/summary/PhaseSeparationA page feed that is not on the API page.
/summary/UniprotA page feed that is not on the API page.
What the model is told

Fetch the curated functional-disorder context that is loaded by the Summary page but is not part of the base summary bundle: DisProt regions (term, namespace, evidence and spans), LLPSdb/PhasePDB protein and region records, DIBS/MFIB/PhasePro disorder-binding regions, MaveDB/ProteinGym assay coverage, UniProt ROI/binding annotations, and the same entry-level UniProt Function/Subcellular location/Disease prose shown in Summary. Use for LLPS/phase separation, condensates, experimentally curated disorder function, MAVE assay evidence, or UniProt functional-region questions. It reports data availability explicitly: no returned record means only that this DisCanVis layer has no record, not that the biology is absent. Args: identifier, search_type. search_type is one of 'gene_name' (e.g. 'CTNNB1'), 'uniprot' (e.g. 'P35222'), 'transcript' (Ensembl 'ENST...'), 'gencode' (GENCODE protein accession), or 'ensembl' (Ensembl gene 'ENSG...'). Pick the one that matches the identifier the user gave.

tool get_uniprot_entry

The UniProtKB entry text the Summary UniProt card shows.

Parameters
NameTypeRequiredDefaultMeaning
identifierstringrequired—The protein: a GENCODE accession (RAF1-201), a gene symbol, a UniProt accession or an Ensembl transcript, as named by search_type.
search_typestringoptional'gencode'What identifier is: gencode (the default), gene_name, uniprot or transcript. A gene with several isoforms answers with its main isoform.
Returns

Protein name, Function, Catalytic activity, Pathway, Subcellular location, Disease, Interaction and keywords. Entry-level prose, not a residue annotation.

Wraps
RequestOn the API page
/rest/{id}.jsonGET /rest/{id}.{format}

Also reads outside the site: UniProt REST, for the entry text.

What the model is told

Fetch the textual UniProtKB entry information that the Summary page's live UniProt card displays: protein name, Function, Catalytic activity, Pathway, Subcellular location, Disease, Interaction and keywords. Use when explaining molecular role or pathway context for a mutation/IDR/motif result; this is entry-level functional prose, not a residue-level annotation. Args: identifier, search_type. search_type is one of 'gene_name' (e.g. 'CTNNB1'), 'uniprot' (e.g. 'P35222'), 'transcript' (Ensembl 'ENST...'), 'gencode' (GENCODE protein accession), or 'ensembl' (Ensembl gene 'ENSG...'). Pick the one that matches the identifier the user gave.

tool get_protein_go

The Gene Ontology terms of one protein, by aspect.

Parameters
NameTypeRequiredDefaultMeaning
identifierstringrequired—The protein: a GENCODE accession (RAF1-201), a gene symbol, a UniProt accession or an Ensembl transcript, as named by search_type.
namespacestringoptionalemptymolecular_function, biological_process or cellular_component; empty returns all three.
containsstringoptionalemptyA word or GO id the term must contain, for example kinase.
Returns

Molecular function, biological process and cellular component, with a count per aspect; at most 25 terms per aspect are returned, narrowed by namespace or contains.

Wraps
RequestOn the API page
/ajax/protein-go/Autocomplete feed (GO terms of a protein).
What the model is told

Gene Ontology annotations of ONE protein, grouped into molecular_function, biological_process and cellular_component, with a count per aspect. The reverse of get_go_proteins (which lists the proteins carrying one GO term). Use for 'what does X do / where is X located according to GO'. A protein can carry hundreds of biological_process terms: only the first 25 per aspect reach you, so narrow with namespace ('molecular_function', 'biological_process', 'cellular_component') and/or contains (a word or GO id, e.g. 'kinase', 'GO:0000165'). An empty aspect means DisCanVis holds no terms of that aspect for the protein, not that the protein lacks the function. Args: identifier (gene symbol, UniProt or GENCODE accession), namespace (optional), contains (optional).

Position and region

One residue or one stretch of one protein, with the protein's own background beside the counts. Positions are 1-based.

tool get_position

Everything that overlaps one residue of one protein.

Parameters
NameTypeRequiredDefaultMeaning
identifierstringrequired—The protein: a GENCODE accession (RAF1-201), a gene symbol, a UniProt accession or an Ensembl transcript, as named by search_type.
positionintegerrequired—The residue, 1-based.
search_typestringoptional'gencode'What identifier is: gencode (the default), gene_name, uniprot or transcript. A gene with several isoforms answers with its main isoform.
Returns

Motifs, domains, PTMs, the disorder score, germline and somatic variants and predictor scores at that position.

Wraps
RequestOn the API page
/rest/{id}/{model}GET /rest/{id}/{layer}
/rest/{id}/{position}.jsonGET /rest/{id}/{position}.{format}
What the model is told

Fetch all annotations that overlap a SINGLE residue on one protein (/rest/{id}/{position}.json). Returns motifs, domains, PTMs, disorder score, mutations (TCGA/COSMIC/cBioPortal/ClinVar) and pathogenicity predictors intersecting that position. Use as the first step for any single-site question ('what's at CTNNB1 position 32', 'context around SLC2A1 P485') and as a companion to variant_interpret. Coordinates are 1-based on the isoform used by DisCanVis. Args: identifier, position (int), search_type. search_type is one of 'gene_name' (e.g. 'CTNNB1'), 'uniprot' (e.g. 'P35222'), 'transcript' (Ensembl 'ENST...'), 'gencode' (GENCODE protein accession), or 'ensembl' (Ensembl gene 'ENSG...'). Pick the one that matches the identifier the user gave.

tool get_region needs the site's code

Everything in a residue window of one protein, with the window's mutation density against the rest of the protein.

Parameters
NameTypeRequiredDefaultMeaning
identifierstringrequired—The protein: a GENCODE accession (RAF1-201), a gene symbol, a UniProt accession or an Ensembl transcript, as named by search_type.
startintegerrequired—First residue of the window, 1-based.
endintegerrequired—Last residue of the window, 1-based and inclusive.
search_typestringoptional'gencode'What identifier is: gencode (the default), gene_name, uniprot or transcript. A gene with several isoforms answers with its main isoform.
alphamissensebooleanoptionalFalseAlso read AlphaMissense over the window: per-residue mean and highest score, the substitutions by the published bands, the window against the protein's own mean (true/false, default false).
Returns

Disorder, conservation, motifs, ClinVar and TCGA records, significantly mutated regions, and burden_vs_background (records per residue in the window against the rest of the protein in the same disorder context, a ratio, not a test).

Wraps
RequestOn the API page
/rest/{id}/combinedGET /rest/{id}/{layer}
/rest/{id}/tcgamGET /rest/{id}/{layer}
/rest/{id}/{model}GET /rest/{id}/{layer}
/rest/{id}/{start}-{end}.jsonGET /rest/{id}/{start}-{end}.{format}

In a standalone server: Leaves burden_vs_background out (available: false): the disorder threshold is read from the site's code.

Example call
{
  "identifier": "RAF1-201",
  "start": 250,
  "end": 265
}
Example result · abridged, RAF1, standalone server
{"tool": "get_region", "summary": "Fetched region 250-265",
 "evidence": {"interval": {"start": 250, "end": 265},
              "disorder": {"combined_disordered_fraction": 1.0, "iupred_mean": 0.8526, "mobidb": "Experimental Disorder", …},
              "phastcons": {"mean": 0.9999, "minimum": 0.998, "maximum": 1.0},
              "tcga_missense": {"S257L": 11, "S259F": 2, "H264Y": 1, "P261R": 1, "S257W": 1},
              "tcga_counts": {"records": 16, "unique_variants": 5, "recurrent_variants": 2, …},
              "mutation_source": "TCGA missense only; cBioPortal and DepMap records are not in this payload.",
              "clinvar": {"records": 52, "unique_variants": 50, "diseases": {"RASopathy": 43, "Noonan syndrome": 18, …}, …},
              "burden_vs_background": {"available": false,
                  "reason": "needs the DisCanVis process (disorder threshold) and a resolved isoform"},
              …},
 "provenance": {"endpoint": "/rest/{id}/{start}-{end}.json", "search_type": "gencode"}, …}

This capture is from a standalone server: without the site's own code burden_vs_background says it is not available. Inside the site (AI Chat) it holds the ratio against the protein's own background.

What the model is told

Fetch all annotations restricted to a residue window [start..end] on one protein (/rest/{id}/{start}-{end}.json). Coordinates are 1-based inclusive on the isoform used by DisCanVis. Use for coordinate-bound questions ('what's in CTNNB1 30-40', 'annotations in the TP53 N-terminus 1-90', 'AlphaMissense island 449-457 of FOXP2'). Do NOT use for a single residue — call get_position. Do NOT use to scan many proteins — call batch_analyze. This tool already returns disorder, conservation, motifs, clinical records and mutation evidence for the interval: it accepts NO 'model' argument. burden_vs_background compares the interval's TCGA records per residue with the rest of the same protein in the same disorder context (ratio, expected count): use it whenever you state a region's mutation count — a count without that baseline is not a finding — and keep it apart from region_significance, the statistical call. Args: identifier, start (int), end (int), search_type, alphamissense (true reads AlphaMissense over the window: the residues' mean and highest score, the substitutions by its published bands, the window's mean against the protein's own mean, the combined disorder of each residue; set it for any question about AlphaMissense or predictor scores in a stretch. Without it the result carries no predictor score, and that is "not read", never "no scores"; a result whose alphamissense block says available false names why it was not read). The published cutoff (0.564) is per substitution: report `substitutions_in_published_bands` as "n of m substitutions at or above the cutoff", and read the window's mean of residue means only against the protein's own mean; never write that a region, a mean or "every residue" is above the cutoff (a residue is above it only by its own scores, listed in `residues`). search_type is one of 'gene_name' (e.g. 'CTNNB1'), 'uniprot' (e.g. 'P35222'), 'transcript' (Ensembl 'ENST...'), 'gencode' (GENCODE protein accession), or 'ensembl' (Ensembl gene 'ENSG...'). Pick the one that matches the identifier the user gave.

tool get_residue_structures needs the site's code

Which PDB chains resolve one residue.

Parameters
NameTypeRequiredDefaultMeaning
identifierstringrequired—The protein: a GENCODE accession (RAF1-201), a gene symbol, a UniProt accession or an Ensembl transcript, as named by search_type.
positionintegerrequired—The residue, 1-based.
search_typestringoptional'gencode'What identifier is: gencode (the default), gene_name, uniprot or transcript. A gene with several isoforms answers with its main isoform.
Returns

The chains whose resolved segment contains the position, with the entry, chain and span, and whether the residue is disordered on its own and ordered in the complex. No chain is not 'no structure', and a resolved residue is not an interface residue.

Wraps
RequestOn the API page
/rest/{id}/combinedGET /rest/{id}/{layer}

In a standalone server: Reads the PDB segments from the database: answers Not available from a standalone server.

What the model is told

Which PDB chains resolve one residue: the chains whose resolved segment (PDBRegional, SIFTS, 1-based) contains the position. Cheap (one indexed query for one protein). Use it to say whether a residue has any structure at all, and as the first look before asking for partners: if no chain resolves the residue, no shared-entry interface span can contain it. "No chain resolves this residue" is not "the protein has no structure", and a resolved residue is not an interface residue (get_interface_mutations and get_ppi_context say which complexes). Args: identifier, position (1-based), search_type (as for get_region). The result also says whether the residue is disordered on its own (`disordered_here`, combined disorder) and in which entries it is **ordered in the structure although annotated disordered** (`transition_entries`: a disordered run of 10 or more residues inside the chain's resolved span, the Disordered+PDB region set). That is a disagreement between the disorder annotation and the solved chain, not a folding experiment.

tool get_disease_regions needs the site's code

Where in one protein the variants of one disease sit, against the rest of the protein.

Parameters
NameTypeRequiredDefaultMeaning
identifierstringrequired—The protein: a GENCODE accession (RAF1-201), a gene symbol, a UniProt accession or an Ensembl transcript, as named by search_type.
diseasestringrequired—A disease name or a MONDO id, matched among the protein's own disease terms.
search_typestringoptional'gencode'What identifier is: gencode (the default), gene_name, uniprot or transcript. A gene with several isoforms answers with its main isoform.
Returns

ClinVar pathogenic and likely pathogenic missense records of that disease placed in Pfam domain blocks and the stretches between, each region with its count against the protein's own background. An ambiguous disease name returns the protein's diseases instead of a guess.

Wraps
RequestOn the API page
/rest/{id}/combinedGET /rest/{id}/{layer}
/rest/{id}/{model}GET /rest/{id}/{layer}
/summary/ClinVarA page feed that is not on the API page.
/summary/proteindataA page feed that is not on the API page.

In a standalone server: Needs the site's disorder threshold: answers Not available from a standalone server.

What the model is told

For one protein and one disease, which regions carry that disease's ClinVar variants more than the rest of the protein does? The disease is a name or MONDO id, matched among this protein's own terms (the term and its descendants, as the Summary's disease choice reads it); an ambiguous or unknown name returns the protein's diseases with their record counts instead of a guess. Counts ClinVar pathogenic / likely pathogenic missense records of that disease and places them in Pfam domain blocks and the stretches between them (every residue in exactly one segment), each as records per residue against the rest of the same protein, with the expected count at the protein's average; the disorder split (disordered vs ordered residues) comes first. Other classes of the same disease's records (uncertain, benign, truncating) are named, not counted. The truncating ones (pathogenic frameshift and nonsense) are not placed by residue: a premature stop usually triggers NMD (Nagy & Maquat 1998), a class-level caveat since the exon position is not checked. `census` carries the gene's Cancer Gene Census role (oncogene, TSG, fusion) when it has one. When the answer is about the regions, name the truncating share and the Census role in one sentence, as the report's findings state them (the role beside the class split, never a conclusion about this protein's mechanism). Each segment carries p (exact one-sided binomial test of its records against its share of the protein's residues) and q (Benjamini–Hochberg across the protein's segments): quote them with the ratio and say that records are not independent (recurrent changes), so they are optimistic for hotspot-driven segments. A short segment with one or two records can read high by chance. Args: identifier, disease, search_type (as for get_region). Prefer the disease_regions workflow through run_workflow.

Variants

Place a variant on a protein, then read it: scores with their published cutoffs, frequency, records and the residue it hits.

tool map_genomic_variant

A genomic variant (VCF line, HGVS, rsID) placed on a protein change.

Parameters
NameTypeRequiredDefaultMeaning
querystringrequired—What to place: a VCF id chrom-pos-ref-alt, an HGVS g. or c. expression, or an rsID.
buildstringoptional'auto'auto (decided from the notation, else from which build's reference base matches), GRCh38 or GRCh37.
Returns

The build the coordinate was read in, whether the reference allele matches the genome, the protein change on the transcript the site means, the other transcripts, and the protein and variant to hand to the next tool.

Wraps
RequestOn the API page
/api/genome/resolve/GET /api/genome/resolve/
Example call
{
  "query": "7-140753336-A-T"
}
Example result · abridged, RAF1, standalone server
{"tool": "map_genomic_variant",
 "summary": "7-140753336-A-T → BRAF V600E on BRAF-220 (read in GRCh38, reference matches)",
 "evidence": {"status": "ok", "notation": "genomic",
              "build": {"requested": "auto", "read_in": "GRCh38"},
              "reference_allele": {"checked": true, "matches_genome": true, "stated": "A"},
              "protein_changes": [{"protein": "BRAF-220", "gene": "BRAF", "change": "V600E",
                                   "consequence": "missense", "main_isoform": true, "mane_select": true}],
              "handover": {"protein": "BRAF-220", "gene": "BRAF", "variant": "V600E"}, …},
 "provenance": {"endpoint": "/api/genome/resolve/", "builds": "GRCh38 native, GRCh37 via GENOME_SEGMENTS", "stored": "nothing"}, …}
What the model is told

Place a genomic variant on a protein change before reading it: a VCF line as chrom-pos-ref-alt (3-41224646-C-T, or a pasted VCF row), an HGVS g. or c. expression (NM_001904.4:c.110C>T), or an rsID (rs121913409), in GRCh37 or GRCh38. Reports the build the coordinate was read in (decided from the notation, or from which build's reference base matches, never assumed), whether the reference allele matches the genome there, the protein change on the transcript the site means (main isoform, else MANE Select, else Ensembl canonical), other transcripts, and the change to hand to get_variant_evidence. A reference mismatch usually means the other build; an identifier that names several alleles returns each protein change; a synonymous, truncating or non-coding change is reported as such and not handed over. Nothing is stored. Args: query (one variant), build ('auto' (default), 'GRCh37' or 'GRCh38'). Prefer the genomic_input workflow through run_workflow.

tool get_variant_evidence

Scores and evidence for one named missense change.

Parameters
NameTypeRequiredDefaultMeaning
identifierstringrequired—The protein the change is on, as a gene symbol or accession.
variantstringrequired—One missense substitution, S259F or p.Ser259Phe.
Returns

AlphaMissense and REVEL against their published cutoffs, dbNSFP rankscores, gnomAD frequency, ClinVar and cancer records of that exact change, the residue context, motifs lost or gained, and the ACMG/AMP and somatic oncogenicity readings with their criteria.

Wraps
RequestOn the API page
/analysis/api/upload/interpret/POST /analysis/api/upload/interpret/
/rest/{id}/{model}GET /rest/{id}/{layer}
/variant-interpretation/api/resolve-sequences/Page-internal (the VI form).
What the model is told

Per-variant scores and evidence for ONE named missense change ('RAF1 S259F', 'TP53 p.R175H'). Returns, compactly: AlphaMissense score with its call against the published cutoff; the raw REVEL band used for ACMG PP3/BP4 when available; dbNSFP rankscores for ~40 predictors (REVEL, CADD, SIFT, PolyPhen-2, ESM-1b, …); gnomAD 4.1 allele frequency (status 'not recorded in gnomAD' means it was looked up and is absent, which differs from 'not looked up'); residue context (disorder, conservation, PTMs, annotation spans); ClinVar records at the residue and for this exact change; cancer cohort counts; ELM motifs lost/gained; the automated germline ACMG/AMP reading with its applied criteria; and, beside it, the somatic `oncogenicity` reading (the ClinGen/CGC/VICC oncogenicity SOP: class, points, applied criteria such as OS3/OM3/OP3 with the cancerhotspots.org sample counts, and `leads`). Use this whenever a question asks for a predictor score, population frequency or overall evidence for a specific variant — get_position does not return per-variant scores. dbNSFP rankscores are proteome-wide percentiles: never call one 'pathogenic' against 0.5. The ACMG reading is automated evidence, not a clinical classification; say so. Read BOTH readings and give both, labelled: 'germline ACMG/AMP' and 'somatic oncogenicity' answer different questions (a hereditary disease against a tumour cell's growth advantage) and are never merged or averaged. Lead with the one in `oncogenicity.leads` (somatic when the variant is recorded in tumours or at a cancerhotspots.org hotspot and ClinVar holds no pathogenic record of the exact change, germline otherwise) and state the other beside it. A ClinVar 'conflicting classifications' line is a fact to report, not a reason to call a well-recorded hotspot uncertain; an uncertain somatic class means too little evaluable evidence (functional studies and a known oncogenic change are not evaluated), not absence of oncogenic potential. Quote the points and criteria it returned, nothing more. Report a missing value as missing, never as benign. Give a population frequency as its number, with the population maximum beside it, and do not call it 'rare' or 'common': the only frequency rule applied is ACMG BA1 (at or above 5%); BS1's cutoff depends on the disease and is not evaluated, so say that when the frequency bears on the call. Args: identifier (gene symbol, UniProt or GENCODE accession), variant (e.g. S259F or p.Ser259Phe). Each criterion line ends with `[rule <id>]`: quote the id and call explain_rule for the why. When the residue is disordered and a predictor reading is present, the caveats carry one sentence (rule calib.disorder_caveat): say it once in the answer, beside the predictor, not once per variant.

tool interpret_variants

A list of named missense changes, each read like get_variant_evidence.

Parameters
NameTypeRequiredDefaultMeaning
variantsstringrequired—Named changes, one per line or comma-separated: GRIK2 M867I, SCN2A K908R. At most 25.
Returns

One row per change with the same readings in table form; a change that cannot be placed says why. At most 25 changes per call.

Wraps
RequestOn the API page
/analysis/api/upload/interpret/POST /analysis/api/upload/interpret/
/variant-interpretation/api/resolve-sequences/Page-internal (the VI form).
What the model is told

Read a LIST of named missense changes in one call ('GRIK2 M867I, SCN2A K908R, MYH10 A965V'). Each change is placed on its protein and read exactly as get_variant_evidence reads one: AlphaMissense with its published call, gnomAD 4.1 frequency, ClinVar records for that exact change, the automated germline ACMG/AMP reading with its criteria, the somatic oncogenicity reading beside it (`onc`, `onc_points`, `onc_criteria`; `onc_leads` names the one to lead with), disorder at the residue and ELM motifs lost or gained. Use it whenever a question names two or more variants — do not call get_variant_evidence once per variant. Returns a compact row per variant plus tallies; a change that could not be placed is listed under `failed`, never guessed. Up to 25 changes per call. For one variant's full detail afterwards, call get_variant_evidence or get_motif_delta. The ACMG reading is automated evidence, not a clinical classification; say so. Give the germline and the somatic reading as two labelled readings, never merged; each tally (`acmg_tally`, `onc_tally`) is its own. Explain each code only by its acmg_criteria and acmg_rule (and onc_criteria) (VUS = too few criteria met), never by other columns; a gnomAD frequency is evidence only through BA1, when BA1 is among the criteria. Args: variants (text: gene + change pairs separated by commas, semicolons or new lines; 'GENE:p.Met867Ile' works).

tool compare_substitutions

Two to six different substitutions at one residue, side by side.

Parameters
NameTypeRequiredDefaultMeaning
identifierstringrequired—The protein: a GENCODE accession (RAF1-201), a gene symbol, a UniProt accession or an Ensembl transcript, as named by search_type.
changesstringrequired—Two to six substitutions at one residue, for example S37F S37A S37C.
Returns

Per change: motifs lost and gained, AlphaMissense and REVEL with their cutoffs, gnomAD, ClinVar and cancer records of that exact change as a share of the residue's own records.

Wraps
RequestOn the API page
/rest/{id}/{model}GET /rest/{id}/{layer}
What the model is told

Compare two to six different substitutions at ONE residue side by side (CTNNB1 S37F, S37A, S37C): each is read by the same engine as get_variant_evidence, and the answer gives per change the ELM classes lost and gained, AlphaMissense with its published cutoff, REVEL as a raw score in its published bands (a score between the bands is no call, never a verdict), gnomAD status, the ClinVar records of that exact change, the TCGA and cBioPortal records of that exact change as a share of the residue's own records, and the automated germline ACMG code and the somatic oncogenicity class (`onc`), kept apart. `residue` holds what is the same for every change; `differ_in` names what is not. Changes at different residues are refused: use interpret_variants for a list of variants. Args: identifier (gene or accession), changes (text, e.g. 'S37F S37A S37C'). Prefer the same_position_changes workflow through run_workflow.

tool variant_interpret

The wild type against the mutant sequence: motif membership, disorder and context.

Parameters
NameTypeRequiredDefaultMeaning
payloadobjectrequired—The variant: mutation or variant (D32Y), or position with ref_aa and alt_aa, with the protein in identifier or query. A protein name alone is refused.
payload.querystringoptional—The protein, as a gene symbol or accession.
payload.identifierstringoptional—The protein, as a gene symbol or accession.
payload.mutationstringoptional—The substitution, for example D32Y.
payload.variantstringoptional—The substitution, for example D32Y.
payload.positionintegeroptional—The residue, 1-based, with ref_aa and alt_aa.
payload.ref_aastring (one letter)optional—The wild-type residue, one letter.
payload.alt_aastring (one letter)optional—The mutant residue, one letter.
payload.wt_sequencestringoptional—A wild-type sequence to read instead of the stored protein.
Returns

The Variant Interpretation page's resolve-sequences answer: motifs gained and lost, disorder and, where loaded, LLPS and degron context.

Wraps
RequestOn the API page
/variant-interpretation/api/resolve-sequences/Page-internal (the VI form).
What the model is told

Interpret a specific missense/indel variant: compute WT-vs-mutant differences in motif membership, disorder, and (when available) LLPS / phospho-degron context. Use for 'effect of D32Y in CTNNB1', 'why is SLC2A1 P485L pathogenic', motif GAIN or LOSS questions, and frameshift C-tail consequences (e.g. HMGB1). Pair with get_position for local annotation context. Do NOT use for coordinate-only questions (use get_region) or multi-protein scans (use batch_analyze). Call with a single object argument named 'payload'. Accepted payload forms: {identifier, position, ref_aa, alt_aa} for a missense change, OR {query, mutation} / {identifier, mutation} where mutation is a string like 'D32Y' or 'S45F'. Optional fields: variant, wt_sequence. Do NOT send keys like gene, type, reference_sequence, or nested variant objects. This reads motifs, not classification: for the germline ACMG/AMP and the somatic oncogenicity readings of a variant call get_variant_evidence, and give both, labelled.

tool profile_cohort needs the site's code

A cohort of up to 1 000 variants read with the Analysis upload engine, in-process: tallies, enriched spans, the top rows.

Parameters
NameTypeRequiredDefaultMeaning
datasetanyoptional'my_set'my_set (the variant list attached to the question) or a list of up to 1000 rows: 'GENE change [group]' lines, or objects with protein, change and optional group / sample.
originstringoptional'all'Which class readings are tallied and ranked: all (germline and somatic, side by side, never merged), germline (ACMG/AMP) or somatic (oncogenicity SOP). One of all, germline, somatic.
Returns

Placement (placed, unplaced with reasons), the ACMG/AMP and somatic class tallies with and without a predictor score, disordered against ordered counts with observed over expected against each protein's own background, the spans the engine calls enriched (Benjamini-Hochberg), motifs lost and gained with curated and predicted apart, and at most 25 top rows. The rest of the rows are counted, never returned.

Wraps
RequestOn the API page
/analysis/api/upload/analyze/The upload flow of the Analysis page (session-bound).
/analysis/api/upload/interpret/POST /analysis/api/upload/interpret/

In a standalone server: Runs the Analysis upload engine on the database: answers Not available from a standalone server.

What the model is told

Read a cohort of variants (a disease cohort, a pipeline's output) with the same engine the Analysis *Your data* page runs: placement on a protein and residue, one reading per placed residue, and region enrichment against each protein's own background (Benjamini-Hochberg). Use it for "what does this list of variants say" questions; it takes up to 1 000 rows in one call and a longer list belongs on Analysis. Args: dataset (`my_set`, the default: the variant list attached to the question; or an inline list of `GENE change [group]` lines or `{protein, change, group}` objects), origin (`all`, `germline` or `somatic`: which class readings are tallied and ranked; germline and somatic are two questions and are never merged). You do not receive the rows. The answer is `placement` (placed / unplaced, with the reasons), `classification` (P / LP / VUS / LB / B for germline, O / LO / VUS / LB / B for somatic, each with and without a predictor score), `disorder` (variants in disordered against ordered residues, and observed over expected against the proteins' own disordered share; `—` where no protein has a disorder vector), `enriched_spans` (the spans the engine calls enriched, with kind, evidence curated / predicted / both, observed, expected, O/E and q), `motifs` (lost and gained, specific, and curated against predicted apart) and `top_rows` (at most 25, most damaging class first). Quote a count with its denominator; a span is enriched against this cohort's own uniform background, not against disease. A row with no score keeps its class from the other criteria and is tallied apart: say so, never fill a missing reading. The classes are automated and not clinical classifications. If `placement.unplaced` is not zero, name the reasons.

tool profile_dataset needs the site's code

What is in the reader's own dataset (up to 20 000 placed rows attached to the question): counts, disorder against each protein's own share, region sets, bound disordered regions.

Parameters
NameTypeRequiredDefaultMeaning
datasetstringoptional'my_set'my_set: the dataset attached to the question (the chip). These tools read no pasted text.
Returns

Rows and proteins, the ten proteins with most rows, counts per kind of change, the most frequent residues, changes and substitutions, the disordered share against each protein's own disordered share (the proteome's residue share beside it, as context), the proteins enriched in disorder (exact binomial, Benjamini-Hochberg), the rows in each region set and the rows inside a bound disordered region of the Complexes table. For a set of up to 1 000 rows (or once interpreted) also the germline and somatic class tallies, the rows with a PDB entry and the entries that hold most rows. Never the rows.

Wraps

Reads the region sets, disorder vectors and Complexes spans of the dataset's proteins from the database; the rows are the question's, no request.

In a standalone server: Reads the region sets and disorder vectors from the database: answers Not available from a standalone server.

What the model is told

What is in the reader's own dataset: the placed variants attached to this question (the composer's data chip; up to 20 000 rows, far more than one reading takes). Use it first for "what is in my dataset, and where should I look first?". Args: dataset (`my_set`, the default). You do not receive the rows. The answer is the rows and proteins, the ten proteins with most rows (with their own disordered share, O/E and q), counts per kind of change, the most frequent residues, changes and substitutions, `disorder` (the dataset's rows in disordered against ordered residues, observed over expected against EACH PROTEIN'S OWN disordered share; the proteome's residue share is given as context and is not the test), `region_sets` (rows per annotation set) and `bound_idr` (rows inside an IDR in complex of the Complexes table: a PDB-resolved IDR, co-occurrence in an entry, not a computed interface). Quote a count with its baseline: a count of rows in a region set or a bound region is a count, not a finding; dataset_complexes tests each bound span. A protein with no disorder vector shows `—`, never a default. Next steps: interpret_dataset for the classes and the shortlist, dataset_complexes for the bound regions. For a set of up to 1 000 rows (or once interpret_dataset has run) the answer also carries `interpretation` (how many rows were read), `classes` (the germline ACMG and the somatic oncogenicity tallies, two questions, never merged), `rows_with_pdb` (rows whose residue a chain of a PDB entry resolves), `rows_in_transition_entry` and `pdb_entries` (how many distinct entries, the eight that hold most rows, co-occurrence in an entry, not an interface; `no_residue_data` = entries whose chains have no stored residue data, not counted in either number). Above 1 000 rows without an interpretation it says `not built`: interpret_dataset builds it; do not call a share of the dataset from a profile that did not read the classes. Entries come only from this answer or dataset_rows; name no other PDB id.

tool interpret_dataset needs the site's code

Every placed row of the reader's dataset read with the Analysis upload engine (batches of 500, at most 10 000 rows per run), as tiles and a ranked shortlist.

Parameters
NameTypeRequiredDefaultMeaning
datasetstringoptional'my_set'my_set: the dataset attached to the question (the chip).
scopestringoptional'all'all (the default), disordered, ordered, protein:<accession or gene> or span:<accession or gene>:<start>-<end>; a protein or span is read on its own and leaves the dataset's digest alone.
originstringoptional'all'Which class readings are tallied and ranked: all, germline (ACMG/AMP) or somatic (oncogenicity SOP). One of all, germline, somatic.
Returns

The ACMG/AMP and somatic class tallies, the strongest criteria, motif changes, disordered against ordered, the region sets and the disordered hotspots, and a shortlist of at most 25 rows by a stated rule (P/LP or O/LO first, then motif changes, then disordered residues hit more than once) with drill-down link templates. A run above the cap says how many rows it left out.

Wraps
RequestOn the API page
/analysis/api/upload/interpret/POST /analysis/api/upload/interpret/

In a standalone server: Runs the Analysis upload engine on the database: answers Not available from a standalone server.

What the model is told

Read every placed row of the reader's dataset (`my_set`) with the same engine the Analysis *Your data* Interpret button runs: batches of 500, at most 10 000 rows per run; a longer dataset is read up to the cap in the file's order and the answer says how many rows it left out (name it: never imply the whole dataset was read). The digest of the reading is kept for the session, so a second call is instant. Args: dataset (`my_set`), scope (`all`, `disordered`, `ordered`, `protein:<accession or gene>`, `span:<accession or gene>:<start>-<end>`: a protein or span is read on its own), origin (`all`, `germline` or `somatic`: germline and somatic are two questions and are never merged). You do not receive the rows. The answer is tiles (the ACMG/AMP and oncogenicity class tallies, the strongest applied criteria, motif changes, disordered against ordered, the region sets, disordered hotspots) and a shortlist of at most 25 rows chosen by a stated rule: P/LP or O/LO first, then rows that change a motif, then disordered residues the dataset hits more than once. The shortlist can be shorter than 25 (no more rows meet the rule); say so rather than padding it. Each row is one distinct variant (`same` = how many rows carry it) with `v`, `a`, `pos`, its classes, the strongest criterion, disordered, motif change, `n` (rows at that residue) and `bound` (the IDR in complex that holds it, when one does); the report builds the page links from them, never write a URL. A P/LP share is a share of the dataset, not an enrichment (no baseline). The classes are automated, not clinical. `—` is no reading.

tool dataset_rows

The annotation table of the reader's dataset: at most 25 distinct variants matching a filter, with the PDB entries that resolve each.

Parameters
NameTypeRequiredDefaultMeaning
datasetstringoptional'my_set'my_set: the dataset attached to the question (the chip).
proteinstringoptionalemptyA gene symbol or accession; empty for any.
change_classstringoptionalemptyP, LP, VUS, LB, B (germline) or O, LO (somatic); empty for any. One of , P, LP, VUS, LB, B, O, LO.
in_disorderstringoptionalemptyyes or no; empty for any. One of , yes, no.
region_setstringoptionalemptyPart of a region set's name (for example Pfam); empty for any.
spanstringoptionalemptystart-end residues, for example 175-248; empty for any.
pdbstringoptionalemptyA four-character PDB entry id, for example 1TUP; empty for any.
limitintegeroptional25How many rows to return, at most 25 (the default).
Returns

Per variant the class, strongest criterion, disordered, motif change, AlphaMissense, the annotation spans (at most four names), the PDB entries whose resolved residues hold it (transition entries first) and the bound disordered region, for a protein, class, disorder, region set, span or PDB entry, with the total that matched. Builds the session's interpretation when none exists (a set of up to 25 distinct variants is listed whole).

Wraps

Reads the session's interpretation digest (the server's cache), building it from the placed rows when none exists; no request.

What the model is told

The annotation table of the reader's dataset (`my_set`): per distinct variant the class (germline ACMG, somatic oncogenicity), the strongest criterion, disordered or ordered, the motif change, AlphaMissense, `regions` (the annotation spans over the residue: set, name, span; at most four, `+n` for the rest), `pdb` (the PDB entries whose chain resolves the residue: `8 entries (6 transition): 7XZZ, 8R1F, …`, at most six ids, transition entries first; `(+n with no residue data, listed last)` = entries whose chains have no stored residue data, never counted as resolving it; `no entry` when no chain resolves it, `—` when the entries were not read) and `bound` (the IDR in complex of the Complexes table that holds it). A transition entry (the ◆) is one where the residue is disordered and resolved in the solved entry, which holds a partner protein. Co-occurrence in an entry is not an interface. The report carries the reader's whole table (every row, every entry): list at most 25 rows here, never more than the answer gives, and quote the total that matched. Use it for "show me the annotation table", "which PDB entries resolve my variants", one protein, one class or one span. Filters: protein (gene or accession), change_class (P, LP, VUS, LB, B germline; O, LO somatic), in_disorder (yes / no), region_set (part of a set name), span (`start-end`), pdb (an entry id: the variants that entry resolves). It reads the session's digest and builds it when none exists (a large set takes minutes; the answer says how many rows were read). A set of at most 25 distinct variants is listed whole when no filter is given. The answer says how many more variants match and are not listed. PDB entries in the answer are the ones the tool returned: name no other id.

tool dataset_complexes needs the site's code

The bound disordered regions (IDR in a solved complex) that carry the dataset's variants, each against the dataset's own rows in the protein's other residues.

Parameters
NameTypeRequiredDefaultMeaning
datasetstringoptional'my_set'my_set: the dataset attached to the question (the chip).
limitintegeroptional10How many spans to return, at most 12 (the default is 10).
Returns

Per span: the dataset's rows in it and in the protein, expected, observed over expected, q (Benjamini-Hochberg), the baseline used (own disordered residues, or the named fallback), the entries and first partner, and the complex-view link with the dataset. A span with no baseline says so; no ratio is invented.

Wraps

Reads the Complexes table (DisorderedComplex) and the disorder vectors of the dataset's proteins from the database; no request.

In a standalone server: Reads the Complexes table from the database: answers Not available from a standalone server.

What the model is told

Which IDRs in complex (a run of at least 10 disordered residues inside a PDB entry's resolved residues: co-occurrence in an entry, not a computed interface) carry the reader's dataset (`my_set`), and does the dataset put more variants there than in the protein's other residues? Per span: the dataset's rows in it and in the protein, the expected count, observed over expected, q (Benjamini-Hochberg across the tested spans), the baseline used and the link to the complex view with the dataset marked. The link opens an entry whose resolved residues hold at least one of the dataset's rows in that span, one that maps a partner before one that does not, and says which entry (`entry`) and how many rows it resolves; a span whose rows no entry resolves has no link and says so (`no_entry`): say "no entry resolves this residue", never name another entry for it. The baseline is the dataset's own rows in the protein's OTHER disordered residues; when there are none, the dataset's rows in the protein's other residues, and the answer says "other residues (fallback)": quote that wording, a fallback ratio is not the same claim. A span with fewer than the minimum rows in its protein, or none elsewhere, has no ratio and a reason. "No span holds a row" is not "no structure". O/E says where this dataset clusters, not that the region causes disease. Args: dataset (`my_set`), limit (at most 12).

Motifs

Short linear motifs: what a class is, which instances are the most mutated, and what one substitution does to them.

tool get_motif_class

What a short linear motif class is, as ELM defines it, and how many instances DisCanVis holds.

Parameters
NameTypeRequiredDefaultMeaning
motifstringrequired—A motif class name or identifier, for example LIG_14-3-3_CanoR_1.
Returns

Identifier, type, functional site, description, regex, match probability, binding domains, compartments and processes, and the instance counts per motif source (curated ELM and MoMAP, predicted PEM and ScanSite).

Wraps
RequestOn the API page
/analysis/api/table/GET /api/v1/analysis/table/ (the same view)
/browse/mutation/elm-regex-catalog/Feed of the disabled mutated-regions page.
Example call
{
  "motif": "LIG_14-3-3_CanoR_1"
}
Example result · abridged, RAF1, standalone server
{"tool": "get_motif_class",
 "summary": "LIG_14-3-3_CanoR_1: 14-3-3 binding phosphopeptide motif",
 "evidence": {"classes": [{"elm_identifier": "LIG_14-3-3_CanoR_1", "elm_accession": "ELME000417", "type": "LIG",
                           "functional_site_name": "14-3-3 binding phosphopeptide motif",
                           "regex": "R[^DE]{0,2}[^DEPG]([ST])(…)", "match_probability": 0.00448,
                           "elm_curated_instances": 65, "instances_in_pdb": 16,
                           "class_info": {"interaction_domains": [{"name": "14-3-3", "pfam": "PF00244"}], …}}],
              "instances_by_source": {"ELM": {"instances": 53, "evidence": "curated"},
                                      "MoMAP": {"instances": 0, "evidence": "curated"}, …}},
 "caveats": ["The class description is ELM's; an instance is a candidate site, not demonstrated binding.", …}

An instance is a candidate site, not demonstrated binding: the caveat travels with the answer.

What the model is told

Describe a short linear motif class by name, as ELM defines it: its identifier and accession, type (LIG, DOC, DEG, MOD, TRG, CLV), functional site name, ELM's description, the regex, how specific a match is (match probability), the domains that bind it, where it works (compartments) and the processes it takes part in. Also counts how many instances DisCanVis holds per motif source — curated ELM and MoMAP, predicted PEM and ScanSite — and names the most mutated ones. Use it for "what is / what does the X motif do" questions (LIG_KEPE, "β-TrCP degron", DEG_SCF_TRCP1_1) before answering from memory. Args: motif — an identifier or words of one.

tool rank_motif_instances

The most mutated instances of a motif class across the proteome.

Parameters
NameTypeRequiredDefaultMeaning
motifstringrequired—A motif class name or identifier, for example LIG_14-3-3_CanoR_1.
nintegeroptional5How many to return.
include_predictedbooleanoptionalFalseAlso rank instances predicted by PEM and ScanSite, not only the curated ones.
Returns

At most n sites (merged across sources), each with its TCGA missense records in the span, the ratio to the protein's own residues in the same disorder context, the most recurrent changes and the site's sequence.

Wraps
RequestOn the API page
/analysis/api/table/GET /api/v1/analysis/table/ (the same view)
/browse/mutation/elm-regex-catalog/Feed of the disabled mutated-regions page.
/browse/mutation/slim-scan-sequences/Feed of the disabled mutated-regions page.
What the model is told

Rank the instances of a motif class across the proteome by cancer missense mutations. Searches every motif source — curated ELM and MoMAP, predicted PEM and ScanSite — merges instances of several sources on the same site into one hit, and re-counts each site the same way: TCGA missense records in the span, the ratio to the protein's own residues of the same disorder context, the most recurrent changes, and the site's sequence. Use it for "which X motifs / degrons are the most mutated" questions instead of guessing proteins and scanning them. Args: motif (a class name or its words: an identifier such as DEG_SCF_TRCP1_1, or a bare name such as "β-TrCP degron" or "14-3-3", which resolves to the classes that hold it), n (default 5), include_predicted (true adds a live regex scan of the proteome — slow, only when the annotated sources are too few).

tool get_motif_delta

ELM classes kept, lost and gained across one missense residue.

Parameters
NameTypeRequiredDefaultMeaning
payloadobjectrequired—The variant: mutation or variant (D32Y), or position with ref_aa and alt_aa, with the protein in identifier or query.
payload.querystringoptional—The protein, as a gene symbol or accession.
payload.identifierstringoptional—The protein, as a gene symbol or accession.
payload.mutationstringoptional—The substitution, for example D32Y.
payload.variantstringoptional—The substitution, for example D32Y.
payload.positionintegeroptional—The residue, 1-based, with ref_aa and alt_aa.
payload.ref_aastring (one letter)optional—The wild-type residue, one letter.
payload.alt_aastring (one letter)optional—The mutant residue, one letter.
Returns

The classes before and after (a class that still matches is kept), whether the residue is read as disordered, and the share of the other 19 substitutions that change the same classes.

Wraps
RequestOn the API page
/analysis/api/upload/interpret/POST /analysis/api/upload/interpret/
/variant-interpretation/api/resolve-sequences/Page-internal (the VI form).
What the model is told

ELM classes **kept, lost and gained** across one missense residue — the same scan Variant Interpretation runs (`interpret.motif_scan`), so the chat and the VI page agree. Matches are keyed on the ELM class: a class that still matches after the substitution is *kept*, even if the matched text changed (never report it as lost and gained). `read_here` is false for an ordered residue: the list is shown but a change there is not read as a mechanism. `significance` gives the share of the other 19 substitutions that change as much (small = unusual). A candidate regex hit is NOT proof of binding, trafficking, or pathogenicity: assess disorder, PTMs, conservation and clinical evidence before a mechanism claim. Call with one object argument payload: {identifier, mutation} or {query, mutation}; mutation e.g. 'P485L'. Every class here is a regex match, `evidence_tier` "predicted (regex)", unless it reads "curated ELM instance" (ELM stores an annotated instance at this residue): write "a predicted (regex) LIG_CaM_IQ_9 match", never "a curated ELM class".

Interactions

Partners of a protein, the complexes it shares a structure with, and whether its mutations fall in the interface.

tool get_ppi_context

The PPI page for one protein as data.

Parameters
NameTypeRequiredDefaultMeaning
identifierstringrequired—The protein: a GENCODE accession (RAF1-201), a gene symbol, a UniProt accession or an Ensembl transcript, as named by search_type.
search_typestringoptional'gencode'What identifier is: gencode (the default), gene_name, uniprot or transcript. A gene with several isoforms answers with its main isoform.
Returns

The interaction network, each partner's disorder and mutation burden, shared disease groups, and the partners that share a PDB entry with the protein (co-occurrence in an entry, not a computed contact).

Wraps
RequestOn the API page
/browse/ppi/api/GET /browse/ppi/api/
/summary/api/bundleThe shape the AI Chat tools read (about 2.4 MB); it follows the figure and is not a stable contract.
What the model is told

Fetch the curated PPI Browse context for one protein: the interaction network, partner disorder and mutation burden, shared disease groups, and direct partners co-occurring in annotated PDB complexes. Use for questions about interaction mechanism, a disordered complex, shared disease across partners, or which complex to inspect. This is the rich PPI context tool; do NOT use get_ppi_neighborhood when a raw partner-name list is insufficient. Args: identifier, search_type. search_type is one of 'gene_name' (e.g. 'CTNNB1'), 'uniprot' (e.g. 'P35222'), 'transcript' (Ensembl 'ENST...'), 'gencode' (GENCODE protein accession), or 'ensembl' (Ensembl gene 'ENSG...'). Pick the one that matches the identifier the user gave.

tool get_ppi_neighborhood

The interaction partners of a hub gene, as a plain list.

Parameters
NameTypeRequiredDefaultMeaning
hubstringrequired—The hub: usually a gene symbol, SIAH1.
Returns

The partner gene symbols and accessions with the sources used (IntAct, HIPPIE, BioGRID); the list to feed into the set tools.

Wraps
RequestOn the API page
/ajax/ppi-proteins/GET /ajax/ppi-proteins/
Example call
{
  "hub": "RAF1"
}
Example result · abridged, RAF1, standalone server
{"tool": "get_ppi_neighborhood", "summary": "Fetched PPI neighborhood for RAF1",
 "evidence": {"hub": "RAF1"},
 "provenance": {"endpoint": "/ajax/ppi-proteins/"},
 "data": {"hub": "RAF1", "hub_accession": "RAF1-201", "hub_gene": "RAF1",
          "ppi_sources": ["intact", "hippie", "biogrid"],
          "genes": ["AARSD1", "ABCB5", "ABCD3", …], "count": 482, …}, …}
What the model is told

Return protein-protein interaction partners for a hub gene (/ajax/ppi-proteins/?hub=GENE). Use as the FIRST step of any hub-partner cohort workflow ('disordered partners of SIAH1', 'proteins interacting with TP53'), then feed the results into batch_analyze or per-protein get_protein_full. Args: hub — usually a gene symbol like 'SIAH1'.

tool get_interface_mutations needs the site's code

Whether a protein's mutations sit inside the interface of a solved complex or a binding motif, more than its own background.

Parameters
NameTypeRequiredDefaultMeaning
identifierstringrequired—The protein: a GENCODE accession (RAF1-201), a gene symbol, a UniProt accession or an Ensembl transcript, as named by search_type.
search_typestringoptional'gencode'What identifier is: gencode (the default), gene_name, uniprot or transcript. A gene with several isoforms answers with its main isoform.
partnerstringoptionalemptyOne partner gene to read only the interface shared with it; empty reads them all.
positionintegeroptional0A residue to read on its own; 0 (the default) reads the whole protein.
Returns

TCGA missense and ClinVar pathogenic missense records inside each partner's shared-entry span and inside the curated binding motifs, with the ratio to the protein's background.

Wraps
RequestOn the API page
/rest/{id}/combinedGET /rest/{id}/{layer}
/rest/{id}/{model}GET /rest/{id}/{layer}
/summary/ClinVarA page feed that is not on the API page.

In a standalone server: Needs the site's disorder threshold: answers Not available from a standalone server.

What the model is told

Are a protein's mutations inside the interface spans of its solved complexes, or inside its curated binding motifs, and is that more than the protein's own background? Reads the PPI structural shortlist (partners that share a PDB entry with the protein; the span is the protein's resolved segment in that entry, 1-based) and the curated ELM and MoMAP binding motifs (ligand-binding, docking and degron classes), then counts TCGA missense records and ClinVar pathogenic / likely pathogenic missense records inside those residues per residue against the rest of the same protein (the same disorder context, and the whole rest), with the expected count. The ratio is a density ratio, unstable from a few records: always quote the records and the expected count with it. Each block also carries p (exact one-sided binomial test of the same comparison) and, across partners or motifs, q (Benjamini–Hochberg); records are not independent (recurrent changes), so both are optimistic for hotspots. A span is "co-occurrence in a PDB entry, not a computed contact" (say it so) and can be far wider than the contact; a span that covers most of the protein cannot show enrichment (no ratio is returned when the rest has no records). Args: identifier, search_type (as for get_region), partner (optional gene symbol: read one partner, with every shared entry and its span, e.g. CTNNB1 with BTRC). Prefer the interface_mutations workflow through run_workflow. When the question names a residue (a variant), pass `position`: the reading then says which solved complexes cover that residue (`at_residue`: the partners whose shared entry's resolved hub segment contains it, the entry a curated binding motif there was solved in and the entries where the residue is disordered on its own and ordered in the complex first), or says "No solved complex covers residue N" when none does; the partners that cover it are listed first. An entry that resolves other parts of the protein is not an answer about that residue. Every count is the protein's OWN records in the protein's OWN residues: a partner row ("BRCA2 21–39 · with PALB2", `counts_of`) names the partner that shares the entry, and never counts the partner's residues or variants. Write it as "BRCA2 21–39, the span that binds PALB2, holds 3 ClinVar P/LP records", never "PALB2 carries 3"; the partner's own variants need this tool run on the partner.

tool get_disordered_complexes

Which disordered regions of one protein (or, with no protein, of the proteome) are bound in solved complexes, and whether they are mutated more than the protein's own background.

Parameters
NameTypeRequiredDefaultMeaning
proteinstringoptionalemptyThe protein, as a gene symbol or an accession of any isoform; leave it empty for the proteome-wide table.
originstringoptional'both'somatic (TCGA and cBioPortal), germline (ClinVar pathogenic and likely pathogenic) or both (the default).
limitintegeroptional10How many spans to return: at most 12 for one protein (default 10), at most 25 per origin proteome-wide.
lensstringoptionalemptyProteome-wide only: disease (a disease or tumour-type name), database or region_set; an unknown lens is refused.
valuestringoptionalemptyThe lens's value: a disease name, ClinVar P/LP / ClinVar all / TCGA / cBioPortal / COSMIC, or all / ELM / MoMAP / DisProt.
Returns

One row per bound disordered span (a run of at least 10 disordered residues inside a PDB entry's resolved residues: co-occurrence in an entry, not a computed interface): the partners and entries, the records, expected count, observed over expected, p and q of the somatic and the germline origin (or the reason there is no ratio), the diseases and tumour types, and the ELM, MoMAP, DisProt, Pfam and PTM annotations in the span, with the link to the complex's page. With no protein: the Complexes table's top rows proteome-wide, one ranked list per origin, narrowed by lens and value.

Wraps
RequestOn the API page
/browse/complexes/annotations/Page-internal: the ELM / MoMAP / DisProt / Pfam / PTM annotations overlapping a span, for the Complexes detail's chips.
/browse/complexes/data/Feed of the Complexes table (one row per protein × disordered span in a solved complex).
/rest/{id}/combinedGET /rest/{id}/{layer}
What the model is told

For one protein, which of its disordered regions are bound in solved complexes, and are those regions mutated more than the rest of the protein's disordered residues? Reads the Complexes table of Browse (one row per protein and "IDR in a complex" span: a run of at least 10 disordered residues inside a PDB entry's resolved residues, the entries that carry it grouped inside the row). A span is "co-occurrence in a PDB entry, not a computed interface" (say it so); "no row" is not "no structure" and not "no interaction". Each span carries the partner genes (the protein's own gene is never one), the entries with their spans, and for BOTH origins the records, the expected count, the ratio O/E, p and q: somatic = TCGA + cBioPortal missense, germline = ClinVar pathogenic / likely pathogenic. O/E is the span's records over the records expected at the rate of the protein's own OTHER disordered residues [rule stats.region_enrichment], so it is a ratio against the protein's own background, never a raw count. Each reading names its `baseline`: "own_disordered" (the usual one) or "other_residues" — when the protein's other disordered residues carry no record of that origin, the span is read against the protein's OTHER residues, ordered and disordered outside the span [rule complex.fallback_baseline]; say so in words whenever you quote such a ratio ("against the protein's other residues, because its other disordered residues carry no germline record"), and never compare a fallback ratio with an own-disordered one as if they were the same measure. A span whose ratio is missing carries the reason ("no records in the protein's other disordered residues, nor in its other residues"): state it, and do not read the records as a finding or call the span enriched or depleted. q is Benjamini–Hochberg across the protein's spans and records are not independent (recurrent changes), so it is optimistic for hotspot spans. Disorder is the site's combined disorder at its threshold [rule disorder.threshold]. Each span also lists the diseases (germline) and tumour types (somatic), the region sets and `annotations` that overlap it (ELM, MoMAP, PEM, ScanSite, DisProt, DIBS, MFIB, PhaSePro, LLPS, Pfam and the PTM types with positions; each set names its `evidence` class, and ANCHOR / AIUPred binding come as a score block: max, mean, the residue of the max), and `open`, the link to the complex's page. Rows come ordered by q then O/E (the better origin of each span when origin is both): the first row is where to look first, and "the only" or "all" about the list is true only of the rows returned (`n_complexes` counts them all). Args: protein (gene symbol or accession), origin (somatic, germline or both, the default), limit (at most 12). Prefer the bound_regions workflow through run_workflow. With NO protein the tool answers the proteome-wide question ("which proteins' bound IDRs are most enriched"): the Complexes table's top rows, ordered by q then O/E, one ranked list per origin (`rankings.somatic`, `rankings.germline`; both when origin is both). Each row is the span of ONE protein read against that protein's own background, so say "top by q, each against its own protein", never "most mutated in the proteome". `lens` (disease | database | region_set) and `value` narrow the table (database: ClinVar P/LP, ClinVar all, TCGA, cBioPortal, COSMIC; region_set: all, ELM, MoMAP, DisProt, PEM, ScanSite, DIBS, MFIB, PhaSePro, LLPS, or a group: "Curated motif" (ELM, MoMAP), "Predicted motif" (PEM, ScanSite), "Any motif"; disease: a disease or tumour-type name); an unknown lens or value is refused with the valid ones, never replaced. limit is at most 25 here. `n_complexes` counts the table's rows for the lens and origin; `page` opens the Complexes page (the lens and value are set on the page itself). Proteome-wide rows carry no per-span annotations: read one protein with protein=. Is there a motif in a bound span? Ask with `lens=region_set` and a value (also WITH a protein: then only that protein's spans that overlap an instance of the set come back; "none overlaps" is said as such and is not "no bound span" nor "no motif on the protein"). The answer names the evidence class (`region_set_lens.evidence`, each row's `region_set_evidence`): CURATED (ELM, MoMAP, DIBS, MFIB, PhaSePro, DisProt: a curator recorded it from experiment or literature), PREDICTED (PEM, ScanSite: a method placed it on the sequence, a candidate site, not observed binding), BOTH (LLPS: curated entries beside computed IDR / LCR stretches). Say the class in the sentence ("a predicted PEM motif overlaps this span") and never present a predicted instance as established binding; an overlap is not proof that the instance is the interface. ANCHOR and AIUPred binding are per-residue predictor scores with no cutoff registered in the site: they are never a lens, never a "binding region", only "score max 0.80 at residue 80 (predicted)". The motif lens needs no rebuild: the stored sets (ELM, MoMAP, DisProt) are read from the table, the others by overlap at request time.

tool get_ppi_hubs

The PPI proteome table: which hubs have partners more disordered than the interactome's, a disease cluster, or a solved complex.

Parameters
NameTypeRequiredDefaultMeaning
lensstringoptional'all'all, disordered, cluster, solved or idr: which hubs the table lists; an unknown lens is refused.
groupstringoptionalemptyA disease group (for example Cancer); narrows lens=cluster only.
originstringoptional'somatic'somatic (default) or germline: which origin the hub's own mutated-in-disorder columns read.
min_partnersintegeroptional0A floor on the hub's partner count; 0 (the default) sets none.
limitintegeroptional25How many hubs to return, at most 50 (the default is 25).
Returns

Ranked hubs for one lens (all, disordered, cluster, solved, idr) with the partner count, the disordered-partner O/E and q against the interactome (never the proteome), the hub's own mutated-in-disorder tests, the disease cluster, the solved and IDR-in-complex counts and the link to each hub's page, with the interactome the table was tested against.

Wraps
RequestOn the API page
/browse/ppi/data/Feed of the PPI proteome table (one row per hub with interaction data, its neighbourhood against the interactome; the PpiHubSummary table).
What the model is told

The PPI proteome table as a tool: which hubs of the interactome (one row per main-isoform protein with interaction data, 17,936 of them) have partners MORE DISORDERED than the interactome's, a DISEASE CLUSTER among their partners, a SOLVED complex with a partner, or an IDR in a complex. Use it for proteome-wide interaction questions ("which hubs bind mostly disordered partners", "hubs whose partners share a cancer disease"); for one protein use get_ppi_context. Every neighbourhood number is read against the INTERACTOME, not the proteome (partners are well-studied, disease-annotated proteins: against the proteome 82 of 100 sampled hub tests came out enriched, against the interactome 22): say "against the interactome" whenever you quote a ratio, and quote O/E beside every count. Args: lens (all | disordered | cluster | solved | idr; default all), group (a disease group, only with lens=cluster, e.g. Cancer), origin (somatic | germline: which origin the hub's own mutated-in-disorder columns read; both are returned), min_partners (a floor on the degree, default none), limit (at most 50, default 25). Rows are ordered the lens's own way: disordered by q (smallest first), cluster by cluster q, solved and idr by their counts, all by partners. An unknown lens is refused with the valid ones. Each hub: partners (a degree: an observation that depends on how well the hub is studied), disordered_partners {n, ratio, q, enriched}, partner_disorder_ratio, mutated {somatic, germline} (the hub's own missense in disordered residues, n / in_disorder / ratio / q), disease_cluster {group, partners_in_group, ratio, q}, solved {partners, genes, partners_with_pdb} (co-occurrence in a PDB entry, not a computed interface; "0 solved" and "no partner has a PDB mapping" read differently) and idr_in_complex {spans, best_ratio}; `open` is the hub's page. `interactome` carries the baseline the table was tested against; `total` / `meta` count the lens's rows against the table. `page` is the PPI table page with the same lens. "The only hub" or "all hubs" is true only of the rows returned.

Sets of proteins

Cohorts, GO terms and region sets: the Analysis and Statistics pages as tools.

tool get_analysis_catalog

The datasets, region sets, DisProt terms and ClinVar disease groups the Analysis table can filter by.

Parameters
NameTypeRequiredDefaultMeaning
term_querystringoptionalemptyNarrow the DisProt term list by name or id (for example molecular recognition); empty returns the catalogue.
Returns

The cohort and region-set keys (use them in get_analysis_table), the DisProt terms matching term_query, the ClinVar disease groups and the source list.

Wraps
RequestOn the API page
/api/v1/analysis/catalog/GET /api/v1/analysis/catalog/
What the model is told

Discover the Analysis datasets, region sets, available DisProt IDPO terms and ClinVar disease groups. Use FIRST when identifying an annotation-defined cohort or an unfamiliar dataset/filter. term_query searches loaded DisProt term names or IDs (e.g. 'molecular recognition'); use the returned term_name with get_analysis_table.disprot_term. DisProt curation datasets such as NDDs-related proteins differ from ClinVar disease groups.

tool get_analysis_table

The ranked, pageable Analysis table for a cohort.

Parameters
NameTypeRequiredDefaultMeaning
paramsobjectrequired—The Analysis table query; cohorts and unit are the ones to give. Keys the table does not know are passed on and ignored by it.
params.cohortsstringoptional—Comma-separated cohort keys from get_analysis_catalog.
params.unitstringoptional—protein, region, merged, study or mave.
params.sortstringoptional—A column key; a key the rows do not carry is refused.
params.dirstringoptional—asc or desc.
params.limitintegeroptional—Page size, at most 200.
params.offsetintegeroptional—First row.
params.region_setsstringoptional—Comma-separated region-set keys from the catalog.
params.sourcesstringoptional—Which variant sources to count.
params.disprot_termstringoptional—DisProt term_name discovered with get_analysis_catalog
params.clinvar_disease_groupstringoptional—Disease-specific ClinVar interval counts; requires unit=region; e.g. Neurodegenerative
Returns

leading_rows already in the asked order, the total, the applied sort and the count scope. A sort key the rows do not carry is refused, not ignored.

Wraps
RequestOn the API page
/analysis/api/table/GET /api/v1/analysis/table/ (the same view)
/api/v1/analysis/catalog/GET /api/v1/analysis/catalog/
Example call
{
  "params": {
    "cohorts": "cancer_drivers",
    "unit": "protein",
    "sort": "missense",
    "dir": "desc",
    "limit": 3
  }
}
Example result · abridged, RAF1, standalone server
{"tool": "get_analysis_table", "summary": "Fetched ranked Analysis cohort table",
 "evidence": {"query": {"cohorts": "cancer_drivers", "unit": "protein", "limit": 3, "sort": "missense", "dir": "desc"},
              "total": 857,
              "applied_sort": {"column": "missense", "dir": "desc", "page_in_order": true},
              "leading_rows": [{"protein": "MUC16-201", "gene": "MUC16", "length": 14507, "missense": 3494,
                                "missense_per_residue": 0.241, "driver": "Census", …}, …]},
 "provenance": {"endpoint": "/analysis/api/table/"}, …}
What the model is told

Query the ranked, pageable Analysis table (/analysis/api/table/). Use this for questions asking WHICH proteins in a cohort lead a metric; it uses the same cohort filters and computed sort fields as the Analysis UI, unlike a raw Browse snapshot. For cancer drivers whose missense burden is high in IDRs, call with params {cohorts:'cancer_drivers', unit:'protein', sort:'disordered_missense_per_residue', dir:'desc', limit:25}. The returned leading_rows are already ranked; report those rows and state the metric. For a question about experimentally disordered cancer-driver REGIONS, use {cohorts:'cancer_drivers', unit:'region', region_sets:'Experimental Disorder', sources:'TCGA,cBioPortal', sort:'mutations', dir:'desc', limit:25}. Do not use browse_precompiled when the question requires an ordered/ranked result: its default page may be alphabetical rather than the requested metric. For the most mutated DisProt molecular recognition site in neurodegenerative diseases, first discover the term via get_analysis_catalog, then use {cohorts:'disprot', unit:'region', region_sets:'disprot', disprot_term:<returned term_name>, clinvar_disease_group:'Neurodegenerative', sort:'mutations', dir:'desc', limit:15}. This counts disease-specific ClinVar records within each interval before ranking. Omit sources for all clinical significance classes; use sources:'ClinVar (Pathogenic)' only when pathogenic records are requested. Report the metric, coordinates, counts and ties. Do not substitute ELM motifs, a guessed GO term, or the DisProt NDD curation set for a ClinVar disease group. If every count is zero, report no observed winner in this selection and stop; do not broaden to other annotations or diseases. Quote the actual returned ontology term, including qualifiers such as 'display'. DisProt is a dataset, never a protein identifier in batch roi. A `cohorts` or `region_sets` key that is not in get_analysis_catalog's cohort_keys / region_set_keys is REFUSED (an error naming the valid keys, nothing read): the table no longer falls back to the DisProt default. A tumour type or a disease is not a cohort key: use get_tumour_type_proteins for the proteins of a TCGA / cBioPortal tumour type and get_disease_proteins for a disease name. The singular `cohort` is not a parameter (use `cohorts`). After every call, compare evidence set_label / the rows with what was asked.

tool get_tumour_type_proteins needs the site's code

The proteins that carry the most missense records of one TCGA / cBioPortal tumour type, each against its own residues.

Parameters
NameTypeRequiredDefaultMeaning
tumour_typestringrequired—A TCGA / cBioPortal tumour-type code (BRCA) or its name (breast); an unknown one returns the valid codes.
originstringoptional'somatic'somatic only: a tumour type is a somatic source; a germline disease is get_disease_proteins.
in_disorderbooleanoptionalTrueTrue (the default) ranks by records in disordered residues; false ranks by all records.
limitintegeroptional25How many proteins to return, at most 50 (the default is 25).
sourcestringoptionalemptyTCGA (the default when empty) or cBioPortal: the two are never added.
Returns

Ranked proteins with their records, the records in disordered residues, the protein's own disordered share, observed over expected, p and q (across the proteins listed), the tumour type's own share in disorder beside the proteome's, and the Analysis drill-down link. An unknown tumour type returns the site's tumour types, never a default.

Wraps

Reads the precomputed tumour-type study tables (VariantStudy, VariantStudyProtein) and the disorder profiles from the database; no request.

In a standalone server: Reads the tumour-type study tables from the database: answers Not available from a standalone server.

What the model is told

Which proteins carry the most missense records of one TUMOUR TYPE (a TCGA / cBioPortal code such as BRCA, LUAD, SKCM, or its name: "breast", "Breast invasive carcinoma"), and are those records in disordered residues more than the protein's own residues predict? Use it for "which proteins are mutated in <cancer>", "most mutated in disordered regions in breast cancer". Not for ONE named protein ("are EIF1AX's uveal melanoma mutations concentrated in its tail"): that is the protein's own reading, mutation_hotspots or region_profile. A tumour type is NOT a cohort key: never pass `tcga_brca` or a tumour code as `cohorts` to get_analysis_table (that is refused and reads nothing); this tool is the tumour-type question. An unknown name returns the site's tumour types (code: name): pick one, never guess. `origin` is somatic only (a germline disease question is get_disease_proteins). It reads one source's study: TCGA by default, `source="cBioPortal"` for the other; the two are never added (cBioPortal carries TCGA tumours). Args: tumour_type, origin (somatic), in_disorder (true, the default: rank by records in disordered residues; false: rank by all records, which is where driver genes such as PIK3CA and TP53 lead), limit (at most 50, default 25), source (empty = TCGA). Each protein carries its records, the records in disorder and their share, the protein's own disordered share of residues, `expected` (records x that share), `ratio` (O/E: the in-disorder records over the expected), exact one-sided binomial `p` and `q` (Benjamini-Hochberg across the proteins LISTED, not the proteome). A count with no ratio is not a finding: quote O/E beside every count, and say that ranking by disordered records favours long, mostly disordered genes (MUC16, FLG) whose O/E sits near 1: a ratio near 1 means the records fall where the residues are, not that the protein is a driver. `type_level` gives the tumour type's own share of records in disorder beside the proteome's disordered share of residues. These are RAW record counts: the number of tumours of the type is not stored here, so do not call them patient frequencies. `page` is the Analysis drill-down of the same tumour type (its variants). Prefer the answer's own numbers; a protein not listed is "not among the top N", not "not mutated".

tool get_disease_proteins needs the site's code

The proteins that carry a disease named by a name or part of one, as the Germline diseases page matches it.

Parameters
NameTypeRequiredDefaultMeaning
diseasestringrequired—A disease name or part of one (at least 3 characters), matched as the Germline diseases page matches it.
limitintegeroptional25How many proteins to return, at most 50 (the default is 25).
Returns

Every matched ClinVar / OMIM disease name, then the proteins ranked by their ClinVar pathogenic and likely pathogenic missense records of those names, each with the records in disordered residues, observed over expected against the protein's own disordered share, p and q, and the regions enriched for the disease in the top three; the Germline diseases page link filtered to the name.

Wraps
RequestOn the API page
/rest/{id}/combinedGET /rest/{id}/{layer}

In a standalone server: Reads the Germline diseases tables from the database: answers Not available from a standalone server.

What the model is told

Which proteins carry a DISEASE, named by a name or part of one ("Noonan syndrome", "cardiomyopathy", "Marfan"), and do the disease's ClinVar pathogenic / likely pathogenic missense records fall in disordered residues more than the protein's own residues predict? Use it for "which proteins are linked to <disease>" and "do its variants sit in disordered regions". The match is the Germline diseases page's: a case-insensitive substring of the disease NAMES its two tables list (ClinVar and OMIM); `matched_names` echoes every name that matched, so say which names the answer covers ("Noonan syndrome" matched 37 names, 'Noonan syndrome 1' to '13', 'with multiple lentigines'...). It is not a MONDO group: the 15 organ-system groups (Cancer, Neurodegenerative, ...) are a `clinvar_disease_group` filter of get_analysis_table; a disease name is this tool. Args: disease (at least 3 characters), limit (at most 50, default 25). How it reads: the page's tables give a shortlist (the 30 proteins with the most rows); each is then read exactly (its ClinVar P/LP missense records whose disease name contains the text, split by the combined disorder vector). So `records`, `in_disorder`, `ratio` (O/E against the protein's own disordered share of residues), `p` and `q` (across the proteins listed) are the exact reading; `page_records` is the page's own number and can differ. A depleted disease (PTPN11 and Noonan syndrome: 106 records, 0 in disorder, O/E 0.0x) is a finding too: the test is enrichment-only, so a ratio below one has p near 1; say "depleted", not "no signal". The top three proteins carry `regions`: the regions enriched for the disease (Pfam blocks and the stretches between, q below 0.05) from get_disease_regions, MONDO-rolled-up, so its record count can differ from the name match; call get_disease_regions(protein, disease) for any other protein. ClinVar records carry a disease name and a review level, not proof of causation; a protein not listed is "not among the shortlist", not "unassociated". `page` is the Germline diseases page filtered to the name.

tool rank_disorder_burden needs the site's code

Which proteins of a cohort carry their mutations in disordered residues, each against itself.

Parameters
NameTypeRequiredDefaultMeaning
cohortstringoptionalemptyA cohort key from get_analysis_catalog (cancer_drivers); empty with go set ranks the proteins of that GO term.
nintegeroptional25How many to return.
gostringoptionalemptyA GO identifier: use the proteins of that term as the set.
Returns

Up to n proteins by missense per disordered residue divided by missense per ordered residue, with the disordered and ordered counts and residues beside each ratio, and the set pooled against the proteome. A protein with no ratio is not ranked, and is counted apart.

Wraps
RequestOn the API page
/analysis/api/table/GET /api/v1/analysis/table/ (the same view)
/api/v1/analysis/catalog/GET /api/v1/analysis/catalog/

In a standalone server: Reads the disorder profiles from the database: answers Not available from a standalone server.

What the model is told

Rank a cohort's proteins by how much more their disordered residues are hit than their ordered residues: missense per disordered residue divided by missense per ordered residue, each protein against itself. Use it for "which proteins carry their mutational burden in disorder" questions; a raw per-residue rate favours the long, heavily mutated proteins and does not answer that. Disorder is the combined-disorder vector (DISORDER_THRESHOLD) and the missense (TCGA + cBioPortal + DepMap, each sample counted once: cBioPortal carries TCGA tumours, so repeats are removed, see `sample_dedup`) are split by the same vector. A protein with no vector, no ordered missense or no mutation rows has no ratio and is not ranked. Returns the ratio with both rates and both counts. Args: cohort (a cohort key from get_analysis_catalog, e.g. cancer_drivers), or go (a GO term, e.g. GO:0016567: the proteome narrowed to the term's proteins; a term only defines the set), n (default 25). The answer also carries `reference`: the set pooled as one protein against the proteome pooled as one protein (share of missense in disordered residues, disordered over ordered rate), so a leader is not mistaken for a trend of the whole set. The proteome side is not sample-deduplicated: compare the set with the proteome through `reference.tcga_only` (TCGA alone, the same count on both sides).

tool get_origin_disorder_split needs the site's code

Somatic against germline: the share of missense records in disordered residues, against the share of residues that are disordered.

Parameters
NameTypeRequiredDefaultMeaning
identifierstringoptionalemptyOne protein, as named by search_type; leave empty and give cohort or go to read a set.
cohortstringoptionalemptyA cohort key from get_analysis_catalog (cancer_drivers); empty with go set ranks the proteins of that GO term.
gostringoptionalemptyA GO identifier: use the proteins of that term as the set.
search_typestringoptional'gencode'What identifier is: gencode (the default), gene_name, uniprot or transcript. A gene with several isoforms answers with its main isoform.
Returns

Per source (TCGA, cBioPortal, ClinVar pathogenic, ClinVar benign) the counts in disordered and ordered residues, beside the protein's or set's disordered share and the proteome's.

Wraps
RequestOn the API page
/analysis/api/table/GET /api/v1/analysis/table/ (the same view)
/api/v1/analysis/catalog/GET /api/v1/analysis/catalog/
/rest/{id}/combinedGET /rest/{id}/{layer}

In a standalone server: Reads the mutation rows from the database: answers Not available from a standalone server.

What the model is told

Somatic against germline: the share of a protein's (or a set's) missense records that fall in disordered residues, for TCGA and cBioPortal tumour samples (somatic) and ClinVar pathogenic / likely pathogenic and benign records (germline; benign is the control), each against the share of the residues that are disordered, and beside the proteome's own share. Disorder is the combined-disorder vector at DISORDER_THRESHOLD on the residues and on the records alike. Returns per source the counts in disordered and ordered residues, the share, the baseline, observed over expected, and missense per disordered residue over missense per ordered residue; a source with no records reads "no records", never 0%. TCGA and cBioPortal overlap and are not added; `pooled_somatic` is the one somatic figure (TCGA + cBioPortal + DepMap, each sample counted once, with how many records were repeats). A share from few records is unstable; quote the counts. A set's pooled figure leans on its most mutated members (leading_protein_share). Args: identifier (one protein), or cohort (a cohort key from get_analysis_catalog) or go (a GO term) for a set; search_type as for get_region. Prefer the somatic_vs_germline_idr workflow through run_workflow.

tool get_go_proteins

The proteins annotated with one GO term.

Parameters
NameTypeRequiredDefaultMeaning
go_idstringrequired—A GO identifier, ideally GO:0007623.
Returns

The gene symbols and accessions, the first step of a cohort defined by a GO term.

Wraps
RequestOn the API page
/ajax/go-genes/GET /ajax/go-genes/
What the model is told

Return the list of DisCanVis proteins annotated with a given GO term (/ajax/go-genes/?id=GO:...). Use as the FIRST step of any 'genes in GO term X' cohort workflow (e.g. GO:0007623 circadian rhythm), then feed the accessions into batch_analyze with search_type='gencode'. Do NOT use for PPI expansion (call get_ppi_neighborhood) or as a text search (call browse_dynamic), nor for the GO terms of one protein (call get_protein_go). Args: go_id — a GO identifier, ideally formatted 'GO:0007623'.

tool get_statistics

The cohort roll-ups of the Statistics page.

Parameters
NameTypeRequiredDefaultMeaning
paramsobjectrequired—The query as an object; the keys the tool names are listed below, any other key of the underlying request passes through.
params.setstringoptional—A saved set (human, cancer_drivers, elm, pem, scansite, mfib, dibs, phasepro, disordered_pdb), or go, ppi, protein_list.
params.accessionstringoptional—With set=ppi: the hub (accession, UniProt, gene).
params.go_idstringoptional—A GO identifier, ideally GO:0007623.
Returns

The set, its protein count and the mutation split by category and disorder, with the missense disordered share worked out in evidence.

Wraps
RequestOn the API page
/statistics/api/GET /statistics/api/
What the model is told

Fetch cohort-level roll-up statistics from the Statistics page (/statistics/api/). Use for global questions like '% of cancer drivers mutated through IDRs', 'distribution of disorder in the ClinVar cohort', or any preset summary shown on the Statistics UI. Do NOT use for per-protein questions (use get_protein_full / get_region) or for browsable tables (use browse_*). Args: params — an object of preset/filter keys used by the Statistics page. Recognized filter keys include 'set' (cohort preset), 'accession' (single protein), and 'go_id' (GO-defined cohort); other keys are forwarded to the endpoint.

tool batch_analyze

A multi-protein search: motif scans by regular expression, region or annotation discovery over a list of proteins.

Parameters
NameTypeRequiredDefaultMeaning
payloadobjectrequired—The Batch request (a non-empty object). proteome_wide: true scans the whole proteome with the longer batch timeout and a compact answer.
payload.roistringoptional—Newline-separated identifiers, each optionally identifier start end.
payload.search_modestringoptional—full or region.
payload.search_typestringoptional—What the identifiers are: gene_name, uniprot or gencode.
payload.thresholdnumberoptional—A numeric cutoff of the scan.
payload.accessionsarrayoptional—The proteins as a list of accessions.
Returns

The matched regions and proteins with a compact protein index; proteome_wide scans return a compact hit index (100 hits unless compact_limit says otherwise) instead of the page's full table.

Wraps
RequestOn the API page
/api/v1/batch/analyze/POST /api/v1/batch/analyze/
What the model is told

Run a multi-protein / discovery search against DisCanVis (POST /api/v1/batch/analyze/). Use for proteome or cohort workflows: regex/PSSM motif scans, GO- or PPI-driven cohorts (after get_go_proteins / get_ppi_neighborhood), disorder-fraction filters, and island-pathogenicity statistics. Do NOT use for single-protein questions (use get_protein_full / get_region / get_position) or when the user wants precomputed browse tables (use browse_precompiled or browse_roi_table). Call with a single 'payload' object. Common keys: 'roi' (newline-delimited identifiers, or 'ID start end' rows), 'search_type' (see identifier hint), 'search_mode' ('region' or 'full'), 'discovery_method' ('annotation' or 'prediction'), 'find_region' (e.g. a PEM/ELM class like 'PEM' or 'DEG_SCF_TRCP1_1'), 'columns' (list of column names for the result table), 'accessions' (explicit list). Motif-scan keys: 'motif_mode' ('regex' or 'pssm'), 'regex_input', 'pssm_json', 'pssm_tsv'. For a proteome-wide regex scan with no supplied identifiers, use {proteome_wide:true, search_type:'gene_name', search_mode:'full', discovery_method:'prediction', motif_mode:'regex', regex_input:'...'}. Do NOT put a regex itself in roi or search_type. A proteome-wide regex hit is a sequence-pattern candidate, NOT evidence that the protein is a validated substrate of the named E3 ligase/degron system; report the match count, show a compact representative list, and state that accessibility and experimental evidence are still required. For one named protein's annotated ELM/degron rows, use roi:'GENE', search_type:'gene_name', search_mode:'region', discovery_method:'annotation', find_region:'ELM' exactly once; do not page browse_roi_table repeatedly. Filter keys: 'enforce_disorder_cutoff' (bool), 'disorder_min_percent' (number), 'island_pathogenicity' (bool).

Browse tables

The Browse tables as paged lists: a free-text shortlist, the preset slices, and motif and region rows by mutation burden.

tool browse_dynamic

The Browse table with free-form filters.

Parameters
NameTypeRequiredDefaultMeaning
paramsobjectrequired—Browse filter keys: search (text), page, page_size, and any filter the Search page has.
params.searchstringoptional—Free text.
params.pageintegeroptional—Page number.
params.page_sizeintegeroptional—Rows per page.
Returns

The DataTables rows of the Search table for the given text and paging.

Wraps
RequestOn the API page
/browse/dynamic/data/DataTables feed of the Search table (server-side paging).
What the model is told

Query the DYNAMIC Browse table (/browse/dynamic/data/) with free-form filters — the ad-hoc, filter-as-you-type flavor of Browse. Use when the user wants a custom shortlist that isn't one of the fixed presets (arbitrary text search, combined layer filters). Prefer browse_precompiled for the fast preset tables (driver + MobiDB, driver + AlphaFold, ...). Args: params — filter keys aligned with the Browse UI, e.g. 'search' (text), 'page' (int), 'page_size' (int), plus any Browse filter names.

tool browse_precompiled

The preset Browse slices, for example cancer drivers with experimental disorder.

Parameters
NameTypeRequiredDefaultMeaning
paramsobjectrequired—set names the preset (driver is the Cancer Gene Census table; cancer_drivers and driver_missense_disorder are aliases); friendly paging keys are translated.
params.setstringoptional—The preset slice.
params.datasetstringoptional—The dataset of the slice, where the preset has more than one.
params.pageintegeroptional—Page number.
params.page_sizeintegeroptional—Rows per page.
Returns

The rows of the chosen preset; friendly paging keys are translated to the table's own.

Wraps
RequestOn the API page
/browse/precompiled/data/DataTables feed of the snapshot table.
What the model is told

Query PRECOMPILED Browse tables (/browse/precompiled/data/) — the fast preset slices used for canonical shortlists such as 'cancer drivers with experimental disorder' or 'driver × MobiDB'. Use when the user's question matches a canonical preset. Prefer browse_dynamic for arbitrary ad-hoc filtering. The MCP interface accepts friendly paging keys and translates them to the browser's DataTables API: use params.set='driver' for the Cancer Gene Census driver table (aliases 'cancer_drivers' and 'driver_missense_disorder' also mean this same table); use params.dataset for a named regional snapshot such as 'ELM'. Include page (1-based) and page_size. The returned evidence contains the leading rows: use those records to answer a 'which proteins' question rather than merely describing columns.

tool browse_roi_table

Motif and region rows ranked by mutation burden.

Parameters
NameTypeRequiredDefaultMeaning
paramsobjectrequired—ROI filter keys: search (text), page, page_size, and any filter the Regions table has.
params.searchstringoptional—Free text.
params.pageintegeroptional—Page number.
params.page_sizeintegeroptional—Rows per page.
Returns

The rows of the Regions table for the given text and paging.

Wraps
RequestOn the API page
/browse/roi/data/DataTables feed of the Regions table.
What the model is told

Query the ROI/motif Browse table (/browse/roi/data/) ranked by mutation burden over motif or region-of-interest rows. Use for questions like 'which degrons have the highest TCGA burden', 'top ROIs by ClinVar variants'. Equivalent to running batch_analyze and sorting on mutation columns, but pre-aggregated. Args: params — 'search' (text), 'page' (int), 'page_size' (int), plus ROI filter keys.

Literature

Papers for a gene or a variant that DisCanVis has already placed. They leave the site: both tools read a literature service.

tool check_literature

Papers that annotate a gene, or one variant of it, with the sentences that name it.

Parameters
NameTypeRequiredDefaultMeaning
genestringrequired—The gene symbol, for example RAF1.
variantstringoptionalemptyOne missense substitution, one-letter or three-letter (S259F, p.Ser259Phe).
termstringoptionalemptyA word the quoted sentence must contain (optional).
Returns

Papers found by entity normalisation (PubTator3, Europe PMC as fallback) with PMID and the quoted sentences. A status of unavailable is not 'none'.

Wraps
RequestOn the API page
/ajax/literature/Page-internal literature service (rate-limited upstream).
What the model is told

Papers that annotate a gene, or one protein variant of it, found by entity normalisation (NCBI PubTator3; Europe PMC fallback), with the sentences that mention it. Use it to check a specific claim (gene + variant, or gene + a term such as "degron"), not for general reading. Arguments: gene (symbol, e.g. RAF1), variant (optional, any spelling: S259F, p.Ser259Phe), term (optional word the quoted sentence must contain). For each paper you rely on, quote the sentence, give the PMID, and say whether it supports, contradicts, or only mentions the claim. A paper with no quote is a match in the full text: do not invent what it says. Text-mined literature is evidence of mention, never proof.

tool search_literature

A PubMed search for a gene plus a hypothesis.

Parameters
NameTypeRequiredDefaultMeaning
querystringrequired—What to place: a VCF id chrom-pos-ref-alt, an HGVS g. or c. expression, or an rsID.
max_resultsintegeroptional5How many records, 1 to 10.
Returns

Up to max_results (1 to 10) records: title, PMID, journal, date, authors and the PubMed link. Bibliographic records, not a synthesis.

Wraps

Reads NCBI E-utilities (PubMed) through the site's literature helper.

Also reads outside the site: NCBI E-utilities, through discanvis_server/literature.py.

What the model is told

Search PubMed for primary literature after DisCanVis has identified a concrete variant, region, motif or functional hypothesis. Use only when the user explicitly asks to browse/search literature or asks for papers. Query with the gene plus the evidence-grounded mechanism (for example, 'AFF3 degron variant intellectual disability'). Returns titles, PMIDs, journal/date and PubMed links; do not claim a paper proves a candidate motif unless the paper itself supports that exact claim. Args: query, max_results (1–10).

Workflows

A declared question shape run in one call: its tool steps, the topics checked and the key numbers, each with its baseline.

tool list_workflows

The workflow catalogue.

Parameters

No arguments.

Returns

Each workflow with its question shape, scope, when to use it, the slots it needs and an example. No arguments.

Wraps

Reads the workflow registry in discanvis_mcp/workflows.py; no request.

What the model is told

The catalogue of declared workflows: each is a question shape (A where-does-it-mutate, B variant effect, C region/protein profile, D find proteins, E interaction, F data) with the slots it needs, the scope it answers about, and an example. Call it first when you are unsure whether a workflow fits; then call run_workflow with its id and filled slots. If none fits, use the individual tools and say the answer is exploratory.

tool run_workflow

One declared workflow: validated slots, its tool steps, one report.

Parameters
NameTypeRequiredDefaultMeaning
workflowstringrequired—A workflow id from list_workflows. One of variant_effect, genomic_input, same_position_changes, variant_set, mutation_hotspots, region_profile, disease_regions, bound_regions, tumour_type_proteins, disease_proteins, ppi_hubs, complex_regions_proteome, interface_mutations, interaction_context, somatic_vs_germline_idr, cohort_ranking, motif_ranking, function_profile, interactome_profile, cohort_variants, dataset_profile, motif_scan.
slotsobjectrequired—The workflow's inputs by slot name, for example {"protein": "RAF1", "variant": "S259F"}; the slots of each workflow are in the Workflows table.
slots.proteinstringoptional—A gene symbol or accession.
slots.variantstringoptional—A substitution.
slots.startintegeroptional—First residue (region_profile).
slots.endintegeroptional—Last residue (region_profile).
slots.cohortstringoptional—A cohort key.
slots.proteinsstringoptional—A list of proteins (motif_scan).
slots.regexstringoptional—A regular expression (motif_scan).
slots.go_termstringoptional—A GO identifier.
slots.motifstringoptional—A motif class (motif_ranking).
slots.nintegeroptional—How many to rank (motif_ranking).
slots.diseasestringoptional—a disease name or MONDO id (disease_regions)
slots.partnerstringoptional—one partner gene (interface_mutations)
slots.changesstringoptional—2-6 substitutions at one residue, e.g. S37F S37A S37C (same_position_changes)
slots.querystringoptional—VCF chrom-pos-ref-alt, HGVS g./c., or rsID (genomic_input)
slots.buildstringoptional—auto, GRCh37 or GRCh38 (genomic_input)
Returns

Key numbers each with its basis, the topics used or checked with nothing found, the claims the answer may make, and one line per step saying whether it ran, was skipped or failed.

Wraps

Runs the tools of the workflow, each of which makes its own requests.

What the model is told

Run one declared workflow. Prefer this over assembling the same tools by hand: the steps, the topics checked, the key numbers (each with its baseline or calibration) and the claims the answer may make are fixed by the workflow, and the reader sees which topics were used, checked with nothing found, or not relevant. Arguments: workflow (an id from list_workflows, e.g. variant_effect, genomic_input, same_position_changes, mutation_hotspots, region_profile, disease_regions, bound_regions, tumour_type_proteins, disease_proteins, ppi_hubs, complex_regions_proteome, interface_mutations, interaction_context, somatic_vs_germline_idr, cohort_ranking (a cohort, or the proteins of a GO term), motif_ranking, function_profile, motif_scan (advanced)) and slots (object, e.g. {"protein": "RAF1", "variant": "S259F"}, {"protein": "CTNNB1", "start": 30, "end": 40}, {"protein": "TP53", "disease": "Li-Fraumeni syndrome"}, {"protein": "NFE2L2"} (bound_regions), {"tumour_type": "BRCA"}, {"disease": "Noonan syndrome"}, {"lens": "disordered"} (ppi_hubs), {"protein": "CTNNB1", "changes": "S37F S37A S37C"}, {"query": "NM_001904.4:c.110C>T"}). A variant slot must be a substitution, not a bare position. Answer from the key numbers and step evidence, obey the returned claims, and state any failed or skipped step. For disease_regions, say in one sentence how many of the disease's records are truncating (frameshift, nonsense; not placed by residue, usually NMD) and what the gene's Cancer Gene Census role is, when the report's findings carry them. For bound_regions, "look here first" is the report's last finding, built from the ranked row (O/E and q against the protein's own other disordered residues): quote it as it stands. A span with no ratio is listed with its reason and is not read as a finding. "The only" or "all of" the bound regions is true only of the rows the tool returned; add a hypothesis of your own only as one labelled sentence ("Hypothesis, not in the data"). For tumour_type_proteins, disease_proteins, ppi_hubs and complex_regions_proteome (no protein: a tumour type, a disease, the PPI table, the Complexes table), "look here first" is the report's last finding, from the tool's first enriched row; when none is enriched the finding says there is no row to look at first: quote it, never name a leader of your own. Counts are records, not patients; a protein that leads by count is often just long. The PPI hubs are read against the interactome, never the proteome; the two origins of the bound regions are two lists and are never added.

Rules

The rule index: which guideline criterion, predictor cutoff or house convention was applied, with its authority and source.

tool list_rules

The rule index, as ids by family or as a table of one family.

Parameters
NameTypeRequiredDefaultMeaning
familystringoptionalemptyA rule family (genomic_guideline, disorder_specific, predictor_calibration, house_convention, research) or an id prefix (acmg, onc, calib); empty lists the ids of every family.
Returns

Without family, the ids grouped by family; with one (or an id prefix such as acmg), each rule's id, what it decides, its value and its authority (published, convention or measured).

Wraps

Reads the rule index in discanvis_server/rules.py; no request.

What the model is told

The index of every rule the site applies: which published guideline criterion, which predictor cutoff, which disorder or house convention, each with its authority (published, convention, or measured on the lab's own benchmark) and the value read from where it lives. With no family it returns the ids grouped by family; with a family (genomic_guideline, disorder_specific, predictor_calibration, house_convention, research) or an id prefix (acmg, onc, calib, motif, stats, disorder) it returns the table: id, what it decides, value, authority. Use it for "which rules do you apply" or "show the methodology" (disorder-specific first), then explain_rule for one. Rules marked planned have no value and are never counted. A rule id in a tool result (`[rule acmg.PM1]`) can be quoted in the answer as the id; it is not a [D#] / [M#] handle.

tool explain_rule

One rule: what it decides, its value, authority and source, and where it is applied.

Parameters
NameTypeRequiredDefaultMeaning
rule_idstringrequired—A rule id from list_rules or from a result's [rule ...] tag, for example acmg.PM1.disordered_predicted.
Returns

The statement, the value with its authority and source reference (PMID, DOI or DisCanVis convention), the parts of the site that apply it and, for a criterion, the engine's own text. An unknown id answers no such rule with the nearest ids.

Wraps

Reads the rule index in discanvis_server/rules.py; no request.

What the model is told

One rule in three levels: the one-line statement of what it decides, the value with its authority (published, convention, measured) and its source (a PMID or DOI, or "DisCanVis convention"), and where it is applied (which parts of the site). For an ACMG or somatic criterion the engine's own text on what it reads is added. Call it with the `rule_id` a result carries (`[rule acmg.PM1.disordered_predicted]`, `calib.PP3_BP4`, `calib.AlphaMissense`) when asked why a call was made or where a number comes from; never re-derive a rule in prose. An unknown id answers "no such rule" with the nearest ids. Quote the value and the source as returned; a convention is not a published threshold, and say which it is.

Downloads

The bulk files the Downloads page lists.

tool get_bulk_download_manifest

The Downloads page, as HTML.

Parameters

No arguments.

Returns

The HTML of /access_data in data.html; the file list with sizes and dates is easier to read on the Downloads page itself.

Wraps
RequestOn the API page
/access_dataThe Downloads page (HTML).
What the model is told

Return the /access_data page (HTML) listing pre-joined bulk datasets available for download (e.g. PhasePro × TCGA overlaps, driver × disorder tables). Use only when the user explicitly asks for downloadable files / bulk exports. Do NOT invent file URLs — surface only what the page lists. No arguments.

Workflows

A workflow is a question shape with fixed steps. run_workflow validates the slots, runs the tools in order, and returns the key numbers each with its basis, the topics checked and what the answer may claim. Prefer it to calling the same tools by hand.

WorkflowAnswersSlotsSteps
variant_effect
What is the impact of this variant?
One named missense substitution in one protein. protein, variant get_variant_evidence → get_motif_delta → get_position → get_residue_structures → get_ppi_context (if needed)
genomic_input
What does this genomic variant do?
A variant given as a VCF line, HGVS g. or c. expression, or an rsID (GRCh37 or GRCh38) rather than a protein change. query, build (optional) map_genomic_variant → get_variant_evidence → get_motif_delta → get_position → get_residue_structures → get_ppi_context (if needed)
same_position_changes
How do different substitutions at one residue compare?
Two to six different substitutions at one residue, compared with each other. protein, changes interpret_variants → compare_substitutions → get_position → get_residue_structures → get_ppi_context (if needed)
mutation_hotspots
Where do mutations concentrate, against the protein's own background?
Where variation lands in one protein; hotspots; domain vs tails. protein get_mechanism_overview
region_profile
What characterises this region?
A named stretch of one protein (start–end). protein, start, end get_region → get_functional_context
disease_regions
Which regions carry this disease's variants?
One protein and one disease: where in the protein that disease's ClinVar variants sit, against its own background. protein, disease get_disease_regions → get_summary_bundle
bound_regions
Which disordered regions are bound in solved complexes?
One protein: which of its disordered regions are bound in solved complexes, how they are mutated against the protein's own background, and what to look at first. protein get_disordered_complexes → get_summary_bundle
tumour_type_proteins
Which proteins are mutated in a tumour type, and in their disordered regions?
A tumour type (TCGA code or name) asked for its proteins: which carry the most records, and whether those records sit in disorder more than the protein's own residues predict. tumour_type get_tumour_type_proteins
disease_proteins
Which proteins carry a disease, and where?
A disease name asked for its proteins: which carry its P/LP records, their share in disorder against the protein's own residues, and the enriched regions of the leading proteins. disease get_disease_proteins
ppi_hubs
Which hubs have the most disordered partners, a disease cluster or a solved complex?
The PPI proteome table as a question: hubs whose partners are more disordered than the interactome's, hubs with a disease cluster, hubs solved with a partner. lens (optional), group (optional) get_ppi_hubs
complex_regions_proteome
Which bound disordered regions are the most mutated across the proteome?
The Complexes table with no protein: the bound disordered regions that are the most mutated against their own protein's background, somatic and germline apart. origin (optional) get_disordered_complexes
interface_mutations
Do mutations fall inside the interface of a solved complex?
Whether a protein's mutations sit inside the interface of a solved complex or a binding motif, and more than its own background. protein, partner (optional), position (optional) get_ppi_context → get_interface_mutations
interaction_context
Do variants fall at an interaction interface?
A protein's partners, complexes or an interface. protein, position (optional) get_ppi_context → get_interface_mutations
somatic_vs_germline_idr
Do somatic and germline variants favour disordered regions?
Somatic (cancer) against germline (ClinVar pathogenic) missense in disordered vs ordered residues, for one protein or a set. protein (optional), cohort (optional), go_term (optional) get_origin_disorder_split → get_mechanism_overview
cohort_ranking
Which proteins in a set carry their mutational burden in disorder?
Ranking a named cohort of proteins, or the proteins of one GO term. cohort (optional), go_term (optional) rank_disorder_burden
motif_ranking
Which instances of a motif carry the most mutations?
The most mutated instances of a motif class, across the proteome. motif, n (optional) rank_motif_instances
function_profile
What are this protein's function and localisation?
Function, process or location of one protein (with its disorder share and mutation burden as context). protein get_protein_go → get_uniprot_entry → get_origin_disorder_split → get_functional_context
interactome_profile
Which motifs sit on a hub's partners, and are they mutated more than the partner's own background?
A protein's interaction partners (or the reader's own partner list): which motifs sit on them, curated apart from predicted, and whether they are mutated more than each partner's own background. hub, cohort (optional), n (optional) get_ppi_context → get_analysis_table → get_analysis_table → get_region
cohort_variants
How does my variant list read as a cohort?
The reader's own list of GENE change lines (Analysis Your data, up to 1 000 rows), read as a cohort: placement, classes, disorder against each protein's own share, enriched spans, the top rows. dataset, origin (optional), disease (optional) profile_cohort
motif_scan advanced
Where does a motif pattern match in a set of proteins?
Advanced: a regular-expression motif pattern over a named list of proteins. proteins, regex batch_analyze

Not listed: variant_set, dataset_profile runs from a list the reader attaches in AI Chat, not from slots.

list_workflows
{}

The catalogue: id, question shape, scope, when to use it, the slots and an example.

run_workflow
{
  "workflow": "region_profile",
  "slots": {
    "protein": "RAF1",
    "start": 250,
    "end": 265
  }
}

The slots are validated first; an unknown workflow or a missing slot answers invalid_input.

Settings

Environment variables, with the defaults the code has. The command-line flags of python -m discanvis_mcp.server are --transport (stdio, sse or streamable-http), --host and --port.

VariableDefaultMeaning
DISCANVIS_BASE_URLhttp://127.0.0.1:8001The site the tools read. Point it at a running DisCanVis server.
DISCANVIS_GUIDANCE_RELOAD01 re-reads the tool descriptions when a guidance file changes, without a restart.
DISCANVIS_MCP_BATCH_HTTP_TIMEOUT120Seconds for a proteome-wide batch_analyze scan.
DISCANVIS_MCP_HOSTunsetBind host for sse and streamable-http; the --host flag overrides it.
DISCANVIS_MCP_HTTP_MAX_RETRIES2Retries after a connection error or a 5xx, 408 or 429 answer.
DISCANVIS_MCP_HTTP_RETRY_BACKOFF0.4Seconds before the first retry; doubles each time.
DISCANVIS_MCP_HTTP_TIMEOUT20Seconds one request may take.
DISCANVIS_MCP_PORTunsetBind port for sse and streamable-http; the --port flag overrides it.
DISCANVIS_MCP_TRANSPORTstdiostdio, sse or streamable-http; the --transport flag overrides it.
DISCANVIS_NCBI_API_KEYunsetAn NCBI API key for a higher E-utilities rate limit (optional; never logged). Read by the site's literature helper.
DISCANVIS_NCBI_EMAILunsetA contact address sent to NCBI (optional). Read by the site's literature helper.