Documentation

Helical exposes its platform as a set of tools that your MCP client can call. You describe what you want in your client; it uploads your data to a safe personal project storage, launches the computation job and returns the results. The Helical console is where you buy credits, inspect your files and manage your account.

Project setup and isolation

Every account is linked to exactly one project, created on your first authenticated call. The tool scope is derived from your access token, so there is nothing a client could send that would point a tool at someone else’s data.

Terms and conditions

For additional details, see our terms and privacy policy.

1. Install the plugin

In ChatGPT and Codex, install it from the public plugin directory, where it is listed as Helical. For Claude Code, Claude Desktop and claude.ai, or for custom installations, you can find it on GitHub at helicalAI/heli-plugin.

ChatGPT and Codex

Unified installation – public plugin directory (recommended)

Open the Helical plugin page, choose Install plugin, then Connect to sign in. This step adds the plugin to your OpenAI account, so ChatGPT (web and desktop) and Codex will all pick it up. You can also find it in ChatGPT: open Plugins in the sidebar and look under Public.

From the Codex CLI, you can also add the plugin by running:

codex plugin add helical-platform@openai-curated-remote

Direct from GitHub

If the options above do not work, you can install the plugin directly from our GitHub repository:

codex plugin marketplace add helicalAI/heli-plugin --ref main
codex plugin add helical-platform@helical-marketplace

Claude Desktop, Claude Code and claude.ai

Unified installation – direct from GitHub

In the Claude Desktop app or on claude.ai, add our marketplace via Customize → Plugins → Add → Add marketplace → Add from a repository, and enter helicalAI/heli-plugin. Then, under the Plugins tab, search for Helical and add it. Once that is done, the plugin is installed and available in all the Anthropic apps connected to your account.

Claude Code – direct from GitHub (terminal)

You can also add the plugin from the terminal by running:

claude plugin marketplace add helicalAI/heli-plugin#main
claude plugin install helical-platform@helical-marketplace

2. Connect

Your first call will prompt you to authorise the request and sign in. Use the same account you use on the Helical console, or create one if you do not already have one.

If your client’s access expires, you will be prompted to authorise the connection again. Every connected client is listed under Connections on your Account, where you can also remove its access.

3. Check you are connected

Am I connected, and how much credit do I have?

whoami answers both, and uses no credits:

{"email": "you@example.com", "credits_balance": 12.4821}

This lets you check your balance before you commit to a run. There is also health, which returns {"status": "healthy"} if your authentication is valid.

Once connected, the Walkthrough shows how to run your first job end to end.

Your project is created for you

The first authorised call provisions your project; there is nothing to set up and no name to choose. Every tool then reads and writes inside it, and the project is isolated from other users.

If your client does not have the plugin yet, start with Install & connect.

The example deliberately uses 100 cells and the cheapest model as a first, simple run.

1. Get your data in

Take the first 100 cells of my_data.h5ad, save that as a subset, and upload it to Helical as a dataset

Three calls will happen:

initiateDatasetUpload → completeDatasetUpload → registerDataset

Uploads are multipart: initiateDatasetUpload opens one and hands back part URLs. completeDatasetUpload assembles the parts remotely. registerDataset registers the dataset on the platform and returns a dataset id, which can be reused.

11111111-1111-4111-8111-111111111111

listDatasets lists your datasets and getDataset fetches one by id.

2. Pick a model

Which models can I use?

listModels returns the list of available foundation models, as well as their cost for one job and one cell. The rates are specific to the model used: a larger model will cost more. More information can be found in Credits.

You can name a model, or describe what you are doing and let your client suggest one. This example uses gf-12L-40M-i2048-CZI-CellxGene.

3. Ask for the embedding

Embed that dataset with gf-12L-40M-i2048-CZI-CellxGene

triggerEmbedding takes the dataset id and the model, queues a job and provides a credit cost:

{
  "status": "pending_approval",
  "confirmation_id": "22222222-2222-4222-8222-222222222222",
  "message": "Embedding run queued for approval. Estimated at 100 cells in 1 job, costing at most 0.0202 credits. You are charged when it starts and refunded in full if it fails or is cancelled. ASK THE USER BEFORE APPROVING."
}

The credit cost provided is a ceiling estimate. You are only charged once approved, and any failed run will be refunded.

4. Approve the job

You can then approve the job:

Go ahead

Your client then calls resolveConfirmation with that confirmation id. getConfirmationStatus reports the status of a job you queued.

You can list jobs pending confirmation with listPendingConfirmations in case of interruption.

5. Follow execution

Is it done?

getRunDetails reports one run as it goes. listDagRuns lists all your runs, newest first. Status is running then succeeded. A 100-cell embedding should take minutes. In case of errors, getDagErrors provides details.

6. Collect the result

Download the embedding

This downloads the artifacts once the run has succeeded, in this case a single .npy file:

{
  "artifact_id": "33333333-3333-4333-8333-333333333333",
  "artifact_type": "embedding",
  "display_name": "Embedding output"
}

downloadArtifact provides a signed bearer download link valid for an hour. The shape of the data is one row per cell, in the order of the dataset. The embedding size depends on the model and the job that was run. All files can be found in Files in the Helical console, if you would rather fetch them from a browser.

7. Plot it

Plot a UMAP of that embedding, coloured by condition

This step will happen on your machine, performed by your client.

It needs both files: the embedding for the coordinates, and your original .h5ad for the labels you colour by, which the embedding does not carry.

x = np.load("embedding.npy", allow_pickle=False)
a = ad.read_h5ad("my_data.h5ad")
assert x.shape[0] == a.n_obs and np.isfinite(x).all()

y = umap.UMAP(n_neighbors=15, min_dist=0.1, metric="cosine",
              random_state=42).fit_transform(x)

If it does not run

If you get 402 insufficient_balance, top up your balance in the Helical console. If you encounter an undocumented error, you can reach out to support.

Your MCP client will pick the best tool itself. This page is provided as reference.

Your client first queues the job with triggerEmbedding, then you approve it and your client starts it with resolveConfirmation.

Approval

The triggerEmbedding response tells your client to ask for your approval, so you can approve the job directly in your conversation. This approval is separate from your client’s own permission settings: a client set to auto-approve its actions still cannot approve a job on your behalf.

Following a run and collecting results

listDagRuns and getRunDetails report the status of your runs, and getConfirmationStatus returns the outcome of a job you queued. Once a run has succeeded, downloadArtifact gives you a download link that is valid for an hour.

Files and folders

Work files are not saved, only artifacts relevant to the run. One folder is generated per run.

Downloading results

You can download artifacts through the console or via the link provided to you by downloadArtifact. The link is valid for an hour.

Datasets

Datasets uploaded are not accessible through the console. They are stored on separate, secured storage. See our privacy policy for more details.

Finding a run or artifact

You can search through files using the search box, or using your MCP client.

Credits are the unit all operations on the platform are priced in. Consumption is aligned with the size of models and runs.

Run costs

A run costs a fixed amount for each job, plus its cell count times the per-cell rate. The fixed amount pays for the work every job does before its first cell, so it is the same for ten cells or a million.

You can find the detailed costs in the console.

Credit top-ups

Credits can be acquired in the console with the indicated credit bonus.

Prices are set in US dollars and include taxes. If you are not in the United States, checkout may present the total in your local currency.

Enterprise discounts and Partner credits

For special use cases or for academic labs interested in trying out our platform, you can apply to the Helical Academic Partner Program to obtain free credits. Fill in the research credits form to apply. To discuss larger credit needs, discounts or other partnership opportunities, you can write to partnerships@helical.bio.

Run pricing

Before approving a run, you will be provided with a ceiling credit cost estimate. It will only be charged once approved.

A run that fails or is cancelled is refunded in full, automatically. You will see the original charge and a matching refund against the same run in the console under Usage.

If your balance cannot cover a run, it will be refused. You can top up your account in the console.

Usage and receipts

Your account balance, individual run usage and receipts can be accessed through the console.

Sign-in details

The Details page of your account in the Helical console shows your name and email, and lets you change your password.

Changing your password does not sign out your other devices or connected apps.

To change your name or email, turn on multi-factor sign-in, close your account or delete your uploaded data, contact us.

Connected apps

Connections lists the apps signed in to your account over MCP, such as Codex or Claude Code. Each app shows its access level, when it last signed in, and how many active sign-ins it has. Apps appear here automatically when they sign in, and unused sign-ins expire on their own.

Disabling an app

Disable immediately removes an app’s access on every machine it signed in from. The app will need to sign in again to use Helical. Disable all removes access for every app in the list. Your console session and any running jobs are not affected.