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¶

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.

Related Pages¶

• Setup: Quick Start
• Tool inventory: Tool Catalog
• Exact CLI and JSON formats: Reference