Solitarius MCP

MCP server exposing REINVENT4 generative molecular-design operations as validated, LLM-callable tools. It is compatible with MCP-capable agentic coding platforms such as Claude Code, Codex CLI, Gemini CLI, and others.

Solitarius MCP is the controlled execution interface of Solitarius, a three-layer agentic architecture for computer-aided molecular inverse design:

1. REINVENT4: the molecular-generation and optimisation engine (sampling, transfer learning, staged reinforcement learning).
2. Solitarius MCP (this repository): exposes REINVENT4 operations as validated tools an LLM agent can call through a common interface.
3. Solitarius Agentic System: coordinates specialist agents (Planner, Formulator, Executor, Analyser) that turn a natural-language objective into a traceable molecular-generation campaign.

You can use this server on its own when an agent needs direct access to individual REINVENT4 operations, or together with the orchestration layer when a campaign needs planning, scoring-function formulation, execution, analysis, and iteration.

Prerequisite: you run the server yourself — there is no hosted instance. Either in a conda environment via stdio, or as a Docker HTTP service you build locally (~10–15 min, needs nvidia-container-toolkit). REINVENT4 itself wants an NVIDIA GPU for transfer learning and RL. See Installation.

<div align="center"> <img src="assets/mcp_tool_skill_layer.png" alt="MCP tool and skill layer for the REINVENT4 generative workflow" width="92%"> </div>

The Solitarius MCP interface groups callable operations into input/configuration validation, scoring-component construction and testing, execution, job management, and monitoring and analysis. These tools map agent requests onto REINVENT4 TOML configurations for sampling, transfer learning, and reinforcement learning, and return generated molecules, trained models, optimisation histories, and analysis summaries through the same interface. Lightweight skills provide a direct-instruction alternative for running the same general workflow without the MCP server.

---

Table of Contents

1. Key Features
2. Installation
3. Skills: Lite Mode
4. Troubleshooting
5. Citation

---

Key Features

All long-running tools follow a dry_run → launch protocol that separates workflow construction from computation: the dry run resolves all parameters and returns the complete TOML config without starting REINVENT4, so the agent and user can inspect the model, inputs, and settings before committing resources. After explicit approval, the same validated config is launched and the tool returns the output locations plus a persistent job identifier for monitoring. Outputs land in a timestamped directory (reinvent_runs/<type>_<timestamp>/) with config.toml, reinvent.log, and all result files.

The tools are grouped by their role in a molecular-generation campaign.

Input and configuration

Tool	What it does
reinvent_validate_input	Check (and optionally clean) a SMILES/CSV input file for validity and format issues before it reaches a generator.
reinvent_validate_toml	Validate a complete REINVENT TOML config against the ReinventConfig schema before execution.

Scoring-component construction

Tool	What it does
reinvent_rl_scoring_design_guide	Guide that maps an objective onto supported scoring components, targets, and transforms before an RL configuration is built.
reinvent_custom_scoring_component	Generate a comp_*.py scoring plugin from a description (e.g. "penalize reactive groups") when no built-in component fits.
reinvent_test_scoring_component	Test a custom component against example molecules before wiring it into an RL run.

Execution

Tool	What it does
reinvent_sampling	Sample molecules from a prior or trained checkpoint. Returns SMILES + model likelihoods.
reinvent_transfer_learning	Fine-tune a prior on a focused SMILES dataset, with input validation/cleanup available before launch.
reinvent_reinforcement_learning	Goal-directed optimisation through staged RL with a multi-component scoring function.

Job management

Tool	What it does
reinvent_register_job	Create a persistent record for a launched TL or RL job.
reinvent_attach_pid	Attach the running OS process ID to a registered job.

Monitoring and analysis

Tool	What it does
reinvent_job_status	Poll status (running/completed/failed) of any TL or RL job from its process and log heuristics.
reinvent_plot_rl_history	Plot RL score convergence and per-component trends from a stage CSV. Works mid-run and post-run.
reinvent_analyze_molecules	Evaluate SMILES/CSV: validity, physicochemical properties, druglikeness (QED, Lipinski), scaffold diversity, structural alerts, UMAP projection, optional similarity/novelty vs a reference set. Writes analysis_report.json + per_molecule.csv + PNGs.

Example reinvent_analyze_molecules output: UMAP projection of generated molecules coloured by score, overlaid on a reference set.

---

Installation

Option A: Local stdio

Run the server directly in a conda environment. Supported by all platforms that accept an MCP stdio server.

conda activate reinvent4
pip install -r requirements.txt

# Verify the server imports cleanly (no output = OK)
python -c "import server"

Register with your platform:

# Claude Code
claude mcp add reinvent4 \
  /path/to/miniconda3/envs/reinvent4/bin/python \
  /absolute/path/to/reinvent-mcp/server.py

# With custom plugins / explicit CWD
claude mcp add \
  --env PYTHONPATH=/absolute/path/to/reinvent-mcp/custom_plugins \
  --env REINVENT_CWD=/absolute/path/to/reinvent-mcp \
  reinvent4 \
  /path/to/miniconda3/envs/reinvent4/bin/python \
  /absolute/path/to/reinvent-mcp/server.py

# Codex CLI
codex mcp add reinvent4 -- \
  /path/to/miniconda3/envs/reinvent4/bin/python \
  /absolute/path/to/reinvent-mcp/server.py

# Gemini CLI: ~/.gemini/settings.json
# "mcpServers": { "reinvent4": { "command": "python", "args": ["/absolute/path/to/reinvent-mcp/server.py"] } }

Option B: Docker HTTP (recommended for deployment)

Prerequisites

• Docker Engine with nvidia-container-toolkit
• REINVENT4 cloned into this repo root:

git clone https://github.com/MolecularAI/REINVENT4.git --depth 1 REINVENT4

Build and start

# Generate .env (prompts for your data directory; run once per machine)
bash gen_env.sh

# Create output directories
mkdir -p reinvent_runs custom_plugins/reinvent_plugins/components jobs

# Build the image (~10-15 min first time)
docker compose build

# Start the server
docker compose up -d

# Confirm it's running (expect: "Uvicorn running on http://0.0.0.0:8080" — mapped to host port 8081)
docker compose logs -f

Stop / rebuild

docker compose down
docker compose up -d --build   # rebuild after code changes

Register with your platform

Claude Code — install as a plugin (recommended). This is the only route that also installs the skills; claude mcp add gives you the tools alone.

The container from the previous section must already be running — the plugin declares the server, it does not start it. Install it first and the tools will load but every call will fail to connect.

/plugin marketplace add pregHosh/Solitarius-mcp
/plugin install solitarius-mcp@solitarius

If host port 8081 is already taken and you changed it in docker-compose.yml, point the plugin at the new port instead of editing it:

export SOLITARIUS_MCP_URL=http://127.0.0.1:8082/sse

Or register the server manually (any platform; no skills):

# Claude Code
claude mcp add --transport http reinvent4 http://localhost:8081/sse

# Codex CLI
codex mcp add reinvent4 --url http://localhost:8081/sse

# Gemini CLI
# gemini mcp add -s user --transport http reinvent4 http://localhost:8081/sse

Use --transport http (not --transport sse). The server uses MCP's streamable-http transport (mcp ≥ 1.0); the legacy SSE flag will fail even though the URL path is /sse.

Environment variables

Variable	Default	Purpose
REINVENT_CWD	server directory	Base for resolving relative paths
SERVER_TRANSPORT	stdio	stdio, sse, or streamable-http
SERVER_HOST	0.0.0.0	Bind host (HTTP transports)
SERVER_PORT	8080	Bind port (HTTP transports)
PYTHONPATH	(none)	Must include parent of reinvent_plugins/ for custom components

---

Skills: Lite Mode

skills/ provides slash commands that call the reinvent CLI directly; no MCP server or Docker needed. Requires REINVENT4 on PATH. Supported by Claude Code, Codex CLI, Gemini CLI, and other platforms that load skill/instruction files.

/sample · /rl · /transfer-learn · /analyze · /validate · /job-status · /custom-component

---

Troubleshooting

reinvent: command not found Pass the full env PATH when registering: --env PATH=/path/to/miniconda3/envs/reinvent4/bin:$PATH

ModuleNotFoundError: mcp Run pip install -r requirements.txt inside the reinvent4 conda environment.

Custom component not found

• PYTHONPATH must point to the parent of reinvent_plugins/, not reinvent_plugins/ itself.
• No __init__.py in reinvent_plugins/ or reinvent_plugins/components/.
• Test: python -c "from reinvent_plugins.components import comp_mycomponent"

Tools not appearing

• Run claude mcp list / check your platform's MCP status.
• stdio: python server.py should print Invalid JSON: EOF; that confirms the import succeeded.
• Docker: docker compose ps should show Up, not Restarting.

Failed to connect with Docker Confirm --transport http was used (not --transport sse). Check docker compose ps and docker compose logs.

Port already in use Find the process: ss -tlnp | grep 8081. Kill it or change the host port in docker-compose.yml (8082:8080), then re-register with the new port.

GPU not detected in Docker

docker compose down
docker compose up -d          # must recreate container for GPU deploy config to apply
docker exec reinvent4-mcp nvidia-smi

If nvidia-container-toolkit is missing, install it per the NVIDIA install guide, then sudo systemctl restart docker.

Job status shows completed immediately Status is inferred from the log file. If the log doesn't exist yet, wait a moment and poll again with reinvent_job_status.

---

Citation

If you use Solitarius-MCP or the Solitarius agentic system, please cite:

Solitarius: An Agentic Architecture for Computer-aided Molecular Inverse Design

@article{worakul_solitarius_2026,
    title = {Solitarius: {An} {Agentic} {Architecture} for {Computer}-aided {Molecular} {Inverse} {Design}},
    url = {https://chemrxiv.org/doi/abs/10.26434/chemrxiv.15005834/v2},
    doi = {10.26434/chemrxiv.15005834/v2},
    publisher = {American Chemical Society (ACS)},
    author = {Worakul, Thanapat and Corminboeuf, Clémence},
    year = {2026},
}

This work builds on REINVENT4; please also cite:

@article{loeffler_reinvent_2024,
	title = {Reinvent 4: {Modern} {AI}–driven generative molecule design},
	volume = {16},
	issn = {1758-2946},
	shorttitle = {Reinvent 4},
	url = {https://doi.org/10.1186/s13321-024-00812-5},
	doi = {10.1186/s13321-024-00812-5},
	language = {en},
	number = {1},
	urldate = {2026-07-03},
	journal = {Journal of Cheminformatics},
	author = {Loeffler, Hannes H. and He, Jiazhen and Tibo, Alessandro and Janet, Jon Paul and Voronov, Alexey and Mervin, Lewis H. and Engkvist, Ola},
	month = feb,
	year = {2024},
	keywords = {Generative AI, Reinforcement learning, Transfer learning, Multi parameter optimization, Recurrent neural networks, Transformers},
	pages = {20},
}