Solitarius MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Solitarius MCP Run reinforcement learning to optimize molecules for high QED"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
REINVENT4: the molecular-generation and optimisation engine (sampling, transfer learning, staged reinforcement learning).
Solitarius MCP(this repository): exposes REINVENT4 operations as validated tools an LLM agent can call through a common interface.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.
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
Related MCP server: refua-mcp
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 |
| Check (and optionally clean) a SMILES/CSV input file for validity and format issues before it reaches a generator. |
| Validate a complete REINVENT TOML config against the |
Scoring-component construction
Tool | What it does |
| Guide that maps an objective onto supported scoring components, targets, and transforms before an RL configuration is built. |
| Generate a |
| Test a custom component against example molecules before wiring it into an RL run. |
Execution
Tool | What it does |
| Sample molecules from a prior or trained checkpoint. Returns SMILES + model likelihoods. |
| Fine-tune a prior on a focused SMILES dataset, with input validation/cleanup available before launch. |
| Goal-directed optimisation through staged RL with a multi-component scoring function. |
Job management
Tool | What it does |
| Create a persistent record for a launched TL or RL job. |
| Attach the running OS process ID to a registered job. |
Monitoring and analysis
Tool | What it does |
| Poll status (running/completed/failed) of any TL or RL job from its process and log heuristics. |
| Plot RL score convergence and per-component trends from a stage CSV. Works mid-run and post-run. |
| Evaluate SMILES/CSV: validity, physicochemical properties, druglikeness (QED, Lipinski), scaffold diversity, structural alerts, UMAP projection, optional similarity/novelty vs a reference set. Writes |
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 REINVENT4Build 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 -fStop / rebuild
docker compose down
docker compose up -d --build # rebuild after code changesRegister 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@solitariusIf 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/sseOr 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/sseUse
--transport http(not--transport sse). The server uses MCP'sstreamable-httptransport (mcp ≥ 1.0); the legacy SSE flag will fail even though the URL path is/sse.
Environment variables
Variable | Default | Purpose |
| server directory | Base for resolving relative paths |
|
|
|
|
| Bind host (HTTP transports) |
|
| Bind port (HTTP transports) |
| (none) | Must include parent of |
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
PYTHONPATHmust point to the parent ofreinvent_plugins/, notreinvent_plugins/itself.No
__init__.pyinreinvent_plugins/orreinvent_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.pyshould printInvalid JSON: EOF; that confirms the import succeeded.Docker:
docker compose psshould showUp, notRestarting.
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-smiIf 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},
}Available Tools
13 toolsreinvent_analyze_moleculesA
Evaluate a set of generated SMILES across multiple quality dimensions.
Designed for raw sampling output (CSV or .smi) from reinvent_sampling, but works with any SMILES file. Writes an analysis_report.json and per_molecule.csv to disk and returns a structured summary to the agent.
Evaluators available: Always: validity, physicochemical, druglikeness, scaffold, alerts, diversity With ref: similarity, novelty, coverage (auto-skipped if no ref_smiles_file)
physicochemical covers: MW, LogP, TPSA, HBD, HBA, rotatable bonds, num atoms (incl. H), num heavy atoms, num heteroatoms, fraction heteroatoms, num rings, num aromatic rings, num aliphatic rings. druglikeness covers: QED, Lipinski RO5, Veber rules, SA score (if available). scaffold: Bemis-Murcko scaffold count and diversity. alerts: PAINS and Brenk structural alert rates. diversity: internal diversity (1 − mean pairwise Tanimoto, ECFP4). similarity: nearest-neighbour Tanimoto to reference set. novelty: % generated SMILES not present in reference (exact canonical match). coverage: % reference molecules with ≥1 generated neighbour at Tanimoto ≥ 0.4.
When plots=True, generates PNGs: physicochemical_dist.png — MW/LogP/TPSA/HBD/HBA/QED(/SA) histograms atom_profile.png — num atoms/heavy/hetero/frac_het/rotbonds/rings atom_types.png — element frequency bar chart (C/N/O/S/halogens/…) ring_profile.png — total/aromatic/aliphatic ring histograms similarity_hist.png — NN Tanimoto to ref (if ref provided) umap_projection.png — ECFP4 UMAP; requires umap-learn
Args: smiles_file: Path to sampling CSV or .smi file (SMILES col auto-detected). ref_smiles_file: Optional reference / known-active SMILES file. evaluators: List of evaluator names, or "all" (default). plots: Generate PNG plots (default True). Set False to skip all visualisation. color_by: Property to colour generated UMAP points (viridis). Any column in per_molecule.csv: "qed", "mw", "sa_score", "logp", "tpsa", etc. Default None = generated blue / reference red. output_dir: Where to write outputs (default: _analysis/ next to input).
Inputs: smiles_file (required), plots, color_by, evaluators, +2 more.
reinvent_attach_pidA
Attach a process ID to a registered user job for live polling.
After running a job manually and registering it with reinvent_register_job, call this to attach the PID. The server can then use os.kill(pid, 0) to check if the process is still running, improving polling reliability.
Args: job_id: Job ID from reinvent_register_job pid: Process ID of the running reinvent job
Inputs: pid (required), job_id (required).
reinvent_custom_scoring_componentA
Generate a valid comp_*.py plugin file for REINVENT4.
Based on the canonical template from scoring_function.md. No reinstall needed — REINVENT4 discovers comp_*.py files at runtime.
IMPORTANT: Always provide implementation_code. Write the complete call body as plain unindented Python before calling this tool, then pass it here. Indentation is added automatically. This writes the full implementation in one atomic operation. If omitted, a TODO placeholder is written and the file cannot be edited afterward due to permissions.
When implementation_code is provided, the generated plugin is immediately smoke-tested (import, instantiate, call on sample SMILES, contract check). The test_result appears in the response; on failure, regenerate with corrected implementation_code.
Args: component_name: Python class name (e.g. 'MyQSARModel') description: What this component scores scoring_logic: How to compute the score — plain English, pseudocode, or code parameters: List of {name, type, description} dicts for user-configurable inputs component_tag: '_component' (standard), 'filter' (zeros total if 0), 'penalty' (multiplier) use_molcache: If True, call receives List[Chem.Mol]; else List[str] dependencies: External packages required output_dir: Where to write comp*.py (default: reinvent_plugins/components/) implementation_code: Complete body of call as unindented Python. test_after_generate: Run the smoke test after writing (default True). test_smiles: Override SMILES used by the smoke test. test_params: Per-endpoint parameter values for the smoke test, e.g. {"threshold": 0.5} — scalars are list-wrapped automatically.
Returns file path, source code, TOML snippet, and test_result (when tested).
Inputs: description (required), scoring_logic (required), component_name (required), output_dir, +8 more.
reinvent_job_statusA
Poll the status of any registered REINVENT4 TL or RL job.
Works for both agent-launched and user-registered jobs. Returns: running/completed/failed status, log tail, current epoch, and (on completion) result summaries, top SMILES, checkpoint paths.
Args: job_id: ID from reinvent_transfer_learning, reinvent_reinforcement_learning, or reinvent_register_job
Inputs: job_id (required).
reinvent_plot_rl_historyA
Inspect columns or generate optimisation history plots for a REINVENT4 RL run.
Works mid-run and post-run — plots whatever step data exists at call time. Provide job_id (looks up workdir from registry) OR csv_path directly. job_id takes precedence if both are given.
TWO-CALL PROTOCOL: Call 1 — extra_columns=None (inspect mode): Returns column categorisation (standard, plottable, metadata). No plots are generated. Agent presents plottable_columns to user.
Call 2 — extra_columns=[...] (plot mode): Generates PNGs for Agent, Prior, Target, Score (always) + extra_columns. Saves to output_dir (default: /plots/). Returns paths of all saved PNG files.
Args: job_id: Job ID from reinvent_register_job or reinvent_reinforcement_learning csv_path: Direct path to a stage CSV file (for ad-hoc / finished run analysis) extra_columns: None for inspect; list of column names to plot beyond the standard 4 output_dir: Where to save PNGs (default: /plots/ or <csv_parent>/plots/)
Inputs: job_id, csv_path, output_dir, extra_columns.
reinvent_register_jobA
Register a user-launched REINVENT4 job for status tracking.
Use after running the suggested_cmd yourself. The agent can then poll progress with reinvent_job_status. Optionally attach the process PID with reinvent_attach_pid for live polling.
Args: run_type: 'transfer_learning' or 'staged_learning' workdir: Path to the run's working directory job_id: Optional custom ID (auto-generated if omitted) log_file: Path to log file (default: /reinvent.log) config_path: Path to TOML config (default: /config.toml)
Inputs: workdir (required), run_type (required), job_id, log_file, +1 more.
reinvent_reinforcement_learningA
Run staged reinforcement learning (curriculum learning supported).
If dry_run=True: preview the TOML config without writing or launching. If skip_validation=False (default): validates input SMILES and TOML before proceeding.
Each stage in stages must contain:
scoring: {components: [...], aggregation: "geometric_mean"}
max_score: float
min_steps: int
max_steps: int
Each component in scoring.components:
component_type: str (e.g. "QED", "MolecularWeight", "custom_alerts")
name: str
weight: float (default 1.0)
transform: {type, ...params}
params: dict (component-specific, e.g. smarts list)
is_filter: bool (True for custom_alerts/MatchingSubstructure)
Call reinvent_rl_scoring_design_guide first to collect scoring config interactively.
Set launch=True to have the agent run the job. Set launch=False (default) to get the config + command to run yourself.
Inputs: stages (required), agent_file (required), prior_file (required), sigma, +17 more.
reinvent_rl_scoring_design_guideA
Return the scoring-function design guide for an RL run, with AUTHORITATIVE score transform schemas introspected from the live REINVENT registry.
Use this as the source of truth for transforms: valid_transform_types lists every
accepted transform (8 in REINVENT 4.7.x: sigmoid, reverse_sigmoid, double_sigmoid,
step, left_step, right_step, value_mapping, exponential_decay) and
transform_parameter_schemas gives each one's exact required/optional keys and
defaults. Never use a transform type not in this list.
NOTE: This tool does NOT define scoring component names or their parameter schemas — those are injected separately (in the orchestrator via jobs/component_registry.json, which also carries the test_status / rl_compatible / sync_status readiness gate). Take component names and params from there; route missing components to /custom-component.
Steps: (1) identify objectives, (2) map objectives to components (from the component registry), (3) choose transforms (schemas here), (4) set weights, (5) confirm TOML.
Call this before reinvent_reinforcement_learning to collect the scoring config.
Inputs: no named parameters.
reinvent_samplingA
Generate molecules from a REINVENT4 prior model.
If dry_run=True: preview the TOML config without running. If dry_run=False: runs synchronously (sampling is fast) and returns results immediately.
For libinvent/linkinvent/mol2mol, smiles_file is required.
Generator guide:
reinvent: de novo generation, no input SMILES needed
libinvent: scaffold decoration, provide scaffold SMILES with [*:0] attachment points
linkinvent: fragment linking, provide two warhead SMILES separated by |
mol2mol: analogue generation, provide reference molecule SMILES
Inputs: model_file (required), device, dry_run, workdir, +8 more.
reinvent_test_scoring_componentA
Smoke-test a comp_*.py plugin on sample SMILES without running RL.
Loads the plugin (catching import errors), instantiates the tagged component, calls it on a mix of valid + invalid SMILES, and asserts the REINVENT4 plugin contract (returns ComponentResults with np.ndarray of floats, correct length, NaN for invalid inputs).
Use this after manually editing a comp_*.py, or to re-verify with custom SMILES / parameters. For freshly generated files, the smoke test is already auto-run by reinvent_custom_scoring_component.
Args: file_path: Absolute path to the comp_*.py file (must live under .../reinvent_plugins/components/ so relative imports resolve). test_smiles: SMILES to score. Defaults to a built-in mix of valid + invalid + edge cases. params: Per-endpoint parameter values, e.g. {"threshold": 0.5}. class_name: Component class name. Auto-detected when omitted.
Returns: dict with status (pass/fail), errors, warnings, per-SMILES scores, timing_ms_per_mol, and ready_for_rl flag.
Inputs: file_path (required), params, class_name, test_smiles.
reinvent_transfer_learningA
Fine-tune a REINVENT4 prior on a focused SMILES dataset (transfer learning).
If dry_run=True: preview the TOML config without writing or launching. If skip_validation=False (default): validates input SMILES and TOML before proceeding. Set launch=True to have the agent run the job (returns job_id for polling). Set launch=False (default) to get the config + command to run yourself.
After completion, the output model can be used as agent_file for RL.
Inputs: smiles_file (required), input_model_file (required), device, launch, +12 more.
reinvent_validate_inputA
Validate SMILES/CSV input file before passing to REINVENT4.
Checks line counts, detects duplicates, validates each SMILES with RDKit, and applies generator-specific constraints (attachment points, fragments, etc.).
Args: smiles_file: Path to CSV or SMILES file generator: One of 'reinvent', 'libinvent', 'linkinvent', 'mol2mol' clean: If True, write _cleaned.smi with valid, deduplicated SMILES
Returns: { "valid": bool, "total_lines": int, "valid_smiles": int, "invalid_smiles": int, "duplicates": int, "cleaned_file": str (if clean=True), "errors": [{index, smiles, reason}, ...] (first 10) }
Inputs: smiles_file (required), clean, generator.
reinvent_validate_tomlA
Validate a REINVENT4 TOML config before launch.
Attempts validation via 'reinvent --validate' (preferred) or via REINVENT4's Pydantic ReinventConfig model.
Args: toml_path_or_content: Path to config.toml or TOML content as string is_string: If True, treat input as TOML content
Returns: { "valid": bool, "errors": [{"field": str, "message": str}, ...], "warnings": [str, ...], "config_summary": dict (if valid) }
Inputs: toml_path_or_content (required), is_string.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool has a clearly distinct role in the REINVENT4 workflow: sampling, training, RL scoring design, validation, custom component creation/testing, job management, plotting, and analysis. Even related tools like validate_input and validate_toml target different artifacts, and register_job/attach_pid/job_status cover distinct job lifecycle actions.
All tool names follow the consistent 'reinvent_' prefix with snake_case verb_noun (or clear noun phrase) style, e.g., reinvent_sampling, reinvent_validate_input, reinvent_register_job. The pattern is predictable and aids agent navigation.
13 tools is well-scoped for a specialized REINVENT4 server. Each tool addresses a necessary step in the generation-to-analysis pipeline, and none feel redundant or superfluous.
The toolset comprehensively covers the REINVENT4 lifecycle: generation, transfer learning, RL with scoring design, validation, custom components, job tracking, plotting, and analysis. Minor gaps exist—no tool to list all registered jobs or explicitly stop/kill a job—but these are workarounds via job_status and attach_pid.
Maintenance
Related MCP Connectors
AI-powered bioprotocol optimization — generate, search, and manage lab protocols via MCP
MCP gateway federating 22 biomedical MCP servers behind one endpoint: gnomAD, ClinVar, HPO, VEP.
Agent-to-Agent (A2A) + Model Context Protocol (MCP) hub for peptides.
Agent-to-Agent (A2A) + Model Context Protocol (MCP) hub for peptides.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceAn MCP server that gives LLM agents access to computational protein design tools.19Apache 2.0
- AlicenseNot gradedqualityCmaintenanceMCP server for biological protein design, folding, and affinity prediction using Refua tools, with optional support for ADMET, clinical simulation, preclinical planning, wet-lab automation, and more.MIT
- AlicenseNot gradedqualityCmaintenanceMCP-native scientific skills for reproducible computational biology and AI-driven drug-discovery workflows. It combines deterministic scientific tools with an MCP server to give AI agents real computational capabilities.Apache 2.0
- AlicenseNot gradedqualityCmaintenanceAn MCP server that gives LLMs native access to cheminformatics and molecular ML tools, enabling molecular structure manipulation, descriptor calculation, ML model training, and analysis report generation through natural conversation.37MIT