OmicVerse MCP Runtime and Troubleshooting

This page explains how the server manages data, persistence, cancellation, and logs.

Handles

adata_id

adata_id is the stable MCP handle for a dataset. The dataset itself stays server-side.

  • load with ov.utils.read or ov.datasets.*

  • pass the returned handle to downstream tools

  • persist with ov.persist_adata

  • restore with ov.restore_adata

artifact_id

Plotting and export tools can register files as artifacts. These are referenced by artifact_id.

instance_id

P2 class-backed tools use instance_id for multi-step analyzers such as DEG or metacell workflows.

Handle Types at a Glance

Handle Type

Prefix

Persistable

Example

adata

adata_

Yes

loaded datasets

artifact

artifact_

Yes if file exists on disk

plots, exports

instance

inst_

No

P2 analyzers

Persistence

Use ov.persist_adata to write an .h5ad plus metadata sidecar. Use ov.restore_adata to recover it in a later session.

This is the recommended recovery path across client reconnects or process restarts.

Persistence Example

{"tool_name": "ov.persist_adata", "arguments": {"adata_id": "adata_a1b2c3d4e5f6"}}

{"tool_name": "ov.restore_adata", "arguments": {"path": "/data/ov_persist/adata_a1b2c3d4e5f6.h5ad"}}

Session and Observability

Useful tools:

  • ov.get_session

  • ov.list_handles

  • ov.get_metrics

  • ov.list_events

  • ov.get_trace

  • ov.list_traces

  • ov.get_health

  • ov.get_limits

Example questions:

  • What's the current session status?

  • Show me the recent tool call traces

  • Show me session metrics

  • List all image artifacts from this session

  • Clean up artifacts older than 1 hour, but show me what would be deleted first

  • Export the full artifact manifest as JSON

Example responses often look like:

{
  "session_id": "default",
  "adata_count": 1,
  "artifact_count": 3,
  "instance_count": 0
}

[
  {"trace_id": "abc...", "tool_name": "ov.pp.pca", "duration_ms": 245.3, "ok": true}
]

{
  "adata_count": 1,
  "artifact_count": 3,
  "tool_calls_total": 8,
  "tool_calls_failed": 0,
  "artifacts_registered_total": 3
}

AnnData Inspection

Before asking the model to analyze data, let it inspect the current state:

  • ov.adata.describe

  • ov.adata.peek

  • ov.adata.find_var

  • ov.adata.value_counts

  • ov.adata.inspect

These tools reduce hallucination and make the workflow auditable.

Cancellation and Esc

For adata_id tools, OmicVerse MCP now runs them through a persistent kernel-backed runtime.

That means:

  • the client still sees a normal Running... state

  • the runtime can be interrupted on cancellation

  • the kernel can often be reused after the interruption

  • the goal is to preserve state when possible instead of rebuilding a worker for every tool call

In practice, cancellation depends on the client and the underlying numerical code:

  • if the client sends a proper cancel or disconnect signal, the server can interrupt the current runtime

  • some deep numerical calls may respond slowly to interrupt

  • if the runtime becomes unhealthy, the server may need to recover it before the next request

Logging

stdio

  • protocol traffic uses stdout

  • server logs go to stderr

  • tool call start/end/failure summaries are written to stderr

streamable-http

  • run the server yourself

  • inspect uvicorn and server logs directly

  • this is usually the easiest way to debug connection issues

P2 Lifecycle

P2 tools use a multi-step lifecycle:

  1. create

  2. run or task-specific action such as annotate / train

  3. results or predict

  4. destroy

Example:

ov.bulk.pydeg create -> run -> results -> destroy

instance_id values are memory-only and are lost on server restart.

Limitations

  • P2 tools can appear in listings but still be unavailable at runtime

  • extended-runtime is constrained in some environments

  • local HTTP auth is intended only for localhost development

  • the built-in localhost OAuth flow is memory-only and should not be exposed to untrusted networks

  • the server is effectively single-process for tool execution

  • some long numerical steps may respond slowly to interrupt

  • no result streaming: large outputs are returned as complete results

  • class instances are memory-only and are lost on server restart

  • not every extended dependency stack is available in every environment

Common Problems

Tool is missing

  • verify the --phase you started with

  • ask the client to run ov.list_tools

  • for P2 tools, check ov.describe_tool for dependency availability

adata_id not found

The handle was never created, expired, or belongs to another session. Use ov.list_handles and ov.get_session.

Plot exists but is hard to find

Use:

  • ov.list_artifacts

  • ov.describe_artifact

  • ov.export_artifacts_manifest

Long-running analysis blocks progress

  • prefer local HTTP mode for observability

  • persist the dataset before especially heavy steps

  • use ov.get_trace, ov.list_traces, and ov.list_events to understand what ran

Server crashes or connection is lost

  • inspect stderr or HTTP server logs

  • check stderr for Python tracebacks or import errors

  • restart the MCP server

  • use ov.restore_adata if you had persisted the dataset

Tool is unavailable

  • ask for ov.describe_tool

  • check missing optional dependencies

  • restart after installing missing packages

Remote server connection fails

  • verify SSH connectivity separately, for example ssh -i /path/to/key -p <port> user@host echo ok

  • ensure omicverse[mcp] is installed on the remote machine

  • check the remote Python path in the client config

Preprocessing step fails with missing data requirements

  • the server enforces pipeline ordering

  • follow suggested_next_tools in the error response

  • typical prerequisites are:

    • ov.pp.pca requires layers["scaled"]

    • ov.pp.neighbors requires obsm["X_pca"]

    • ov.pp.umap requires uns["neighbors"]

Server exits immediately

  • ensure mcp>=1.0 is installed

  • if using streamable-http, ensure uvicorn and starlette are installed

Claude Code HTTP connection shows auth/discovery errors

  • make sure the server was started with --transport streamable-http

  • verify the configured URL matches exactly, for example http://127.0.0.1:8765/mcp

  • restart the local MCP server after auth or transport changes because localhost OAuth registrations are memory-only

These observability tools are the first things to use when a workflow behaves unexpectedly.