GitHub
Back to all tutorials

Connect to AI assistants

Connect via MCP

The CellPilot MCP server lets an AI assistant such as Claude Desktop or Codex call CellPilot's analysis tools through natural language. Once connected, you can ask the assistant to load data, run workflows, and interpret results, and it invokes the matching CellPilot tools for you. Every build is a one-step, double-click install: no terminal commands and no config files to edit.

1. Before you start

The MCP download is self-contained, so you do not need the CellPilot desktop app installed. All you need is a desktop AI assistant. The MCP connects to the installed desktop application, not the website:

  • Claude Desktop: install the Claude desktop app from claude.ai/download. The claude.ai browser app cannot load MCP bundles.
  • Codex: install the Codex desktop/CLI tooling from OpenAI. The web version cannot use the MCP server.

2. Download the MCP for your assistant

On the Download page, find the CellPilot MCP for AI Assistants section and pick your assistant (Claude Desktop or Codex). The page auto-detects your Mac's chip and offers the right build; use Other platforms if you need the other one.

Each download is a .zip. This is intentional: browsers can flag raw .mcpb and .dmg files as risky, so we wrap them in a zip. Double-click the downloaded .zip to unzip it before installing.

3a. Install for Claude Desktop

The Claude build is a .mcpb bundle (an MCP bundle Claude Desktop installs in one click).

  1. Unzip the download to get cellpilot-omics-...-mac-0.2.55.mcpb.
  2. Double-click the .mcpb file. Claude Desktop opens and shows an install dialog for the CellPilot extension.
  3. Review the details and click Install (and enable it if prompted).
  4. That's it. CellPilot's tools are now available to Claude.

If double-clicking does not open Claude Desktop, open Claude Desktop first, go to Settings → Extensions, and add the .mcpb file there.

3b. Install for Codex

The Codex build is a macOS installer packaged in a .dmg.

  1. Unzip the download to get CellPilot-Codex-Installer-0.2.61-....dmg.
  2. Double-click the .dmg to mount it, then run the CellPilot Codex Installer app inside.
  3. The installer sets up the CellPilot MCP server for Codex automatically.
  4. Restart Codex so it picks up the new MCP server.

4. Verify the connection

Open your assistant and ask it about CellPilot. If the server is connected, it will list or use CellPilot tools:

What CellPilot tools do you have?
List the CellPilot MCP tools
Use CellPilot to load my dataset

If no CellPilot tools appear, fully quit and reopen the assistant so it reloads the MCP server.

5. Try it out

Once connected, you can ask for analyses in plain language and the assistant will call CellPilot for you:

Load this Cell Ranger output folder and run QC and clustering
Annotate every cluster and suggest cell types
Plot Nphs2 on the spatial view
Find markers for the selected spatial region

This is closely related to CellPilot's built-in Agent Mode. Agent Mode runs inside CellPilot with your own API key; the MCP server instead lets an external assistant (Claude Desktop or Codex) call CellPilot's tools.

Troubleshooting

  • macOS blocks the installer. Right-click the app or .dmg and choose Open the first time to bypass Gatekeeper.
  • Assistant doesn't see CellPilot. Fully quit and reopen the assistant after installing, and confirm you are using the desktop app, not the web version.
  • Wrong architecture. Use the build that matches your Mac (Apple Silicon vs Intel). The Download page detects this automatically.
  • Still stuck? Open an issue on GitHub.