Skip to content

OmicVerse MCP Tool Catalog

The current MCP server exposes up to 58 tools:

  • P0: 15 analysis tools
  • P0.5: 13 additional analysis tools
  • P2: 5 advanced class-backed tools
  • Meta tools: 25 always-on tools

Phase System Overview

Phase Tools Description
P0 15 Core single-cell pipeline, built-in datasets, and essential preprocessing
P0.5 13 Marker genes, pathway analysis, and visualization
P2 5 Advanced class-backed tools
Meta 25 Discovery, AnnData inspection, session, observability, artifacts, safety
Total 58

P0: Core Pipeline & Data Access

Tool Description Key Parameters
ov.utils.read Load a file and return an adata_id path
ov.datasets.pbmc3k Load built-in PBMC3k —
ov.datasets.pbmc8k Load built-in PBMC8k —
ov.datasets.seqfish Load built-in seqFISH —
ov.pp.qc Compute QC metrics adata_id
ov.pp.filter_cells Filter cells adata_id, thresholds
ov.pp.filter_genes Filter genes adata_id, thresholds
ov.pp.log1p Log-transform expression adata_id
ov.pp.highly_variable_genes Identify HVGs adata_id
ov.pp.scale Scale expression and create scaled layer adata_id
ov.pp.pca Compute PCA adata_id, n_pcs
ov.pp.neighbors Build neighbor graph adata_id
ov.pp.umap Compute UMAP adata_id
ov.pp.leiden Leiden clustering adata_id, resolution
ov.pp.louvain Louvain clustering adata_id, resolution

Pipeline order: read or ov.datasets.* -> qc / filtering -> log1p / HVG -> scale -> pca -> neighbors -> umap / clustering

Typical prompts:

  • Load the built-in seqfish dataset
  • Run QC and identify highly variable genes
  • Run PCA with 50 components

P0.5: Analysis & Visualization

Tool Description Key Parameters
ov.single.find_markers Differential marker discovery adata_id
ov.single.get_markers Extract marker table adata_id, n_markers
ov.single.cosg Rank markers with COSG adata_id
ov.single.pathway_enrichment Pathway enrichment marker set or result handle
ov.single.pathway_enrichment_plot Plot enrichment results enrichment result
ov.pl.embedding Generic embedding plot adata_id, color, save
ov.pl.violin Violin plot adata_id, keys, groupby
ov.pl.dotplot Dotplot adata_id, var_names, groupby
ov.pl.markers_dotplot Marker-gene dotplot adata_id
ov.pl.umap UMAP plotting helper adata_id, color
ov.pl.tsne tSNE plotting helper adata_id, color
ov.pl.rank_genes_groups_dotplot Ranked marker dotplot adata_id
ov.pl.marker_heatmap Marker heatmap adata_id

Typical prompts:

  • Find marker genes for each Leiden cluster
  • Run COSG to rank marker genes
  • Perform pathway enrichment on the markers
  • Plot a marker heatmap

P2: Advanced Class-backed Tools

These tools expose a lifecycle such as create -> run -> results -> destroy.

Tool Description
ov.bulk.pydeg Differential expression
ov.single.pyscsa Automated cell annotation
ov.single.metacell Metacell construction
ov.single.dct Differential cell composition
ov.utils.lda_topic Topic modeling

These tools may appear in ov.list_tools but still return tool_unavailable if optional dependencies are missing.

P2 tools use a multi-action lifecycle such as:

  1. create
  2. run / annotate / train
  3. results / predict
  4. destroy

Runtime environment status

OmicVerse validates tool availability against tested dependency stacks:

  • core-runtime: verified (anndata, scanpy, scipy)
  • scientific-runtime: verified (+ scvelo, squidpy)
  • extended-runtime: constrained (SEACells works; mira-multiome is currently blocked)

Use ov.describe_tool to check whether a specific tool can run in your environment.

AnnData Inspection Tools

These tools are important because they let the client inspect the current dataset instead of guessing.

Tool Use
ov.adata.describe High-level summary of shape, names, layers, embeddings, metadata
ov.adata.peek Preview a slot such as obs, var, obsm, layers, or uns
ov.adata.find_var Search var_names for genes such as CD3D
ov.adata.value_counts Count values in an obs column
ov.adata.inspect Inspect nested entries in obsm, obsp, layers, varm, or uns

Typical prompts:

  • Describe the current adata
  • What is the first gene in var?
  • Does CD3D exist in var_names?
  • Show value counts for leiden
  • Inspect adata.obsm X_pca
  • Inspect adata.uns

Meta Tools

Meta tools are always available regardless of phase selection.

Discovery

  • ov.list_tools
  • ov.search_tools
  • ov.describe_tool

Session & Persistence

  • ov.get_session
  • ov.list_handles
  • ov.persist_adata
  • ov.restore_adata

Observability

  • ov.get_metrics
  • ov.list_events
  • ov.get_trace
  • ov.list_traces

Artifacts

  • ov.list_artifacts
  • ov.describe_artifact
  • ov.register_artifact
  • ov.delete_artifact
  • ov.cleanup_artifacts
  • ov.export_artifacts_manifest

Artifact types: file, image, table, json, plot, report, export

Runtime Safety

  • ov.get_limits
  • ov.cleanup_runtime
  • ov.get_health

Dependency Tiers

Tier Packages Tools Unlocked Install
Core anndata, scanpy, numpy, scipy, matplotlib P0 + P0.5 pip install omicverse[mcp]
Scientific + scvelo, squidpy velocity & spatial analysis pip install -r requirements/mcp-scientific-runtime.txt
Extended + SEACells, pertpy P2 class tools pip install -r requirements/mcp-extended-runtime.txt

Checking Your Environment

  • Ask the client to run ov.get_health for a lightweight runtime summary.
  • Ask it to run ov.get_limits for quota and handle usage.
  • Ask it to run ov.describe_tool for one specific tool if you want availability and dependency details.

Choosing Between Similar Tools

  • Prefer ov.datasets.* over file loading when a built-in tutorial dataset is enough.
  • Prefer ov.adata.* before asking the model to infer what is inside obs, var, obsm, or uns.
  • Prefer ov.pl.embedding when you want one generic embedding plotting entrypoint.
  • Use ov.pl.umap or ov.pl.tsne when you want the plot type to be explicit.