Skip to main content
Glama

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.

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


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

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"] } }

Prerequisites

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:

DOI

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 tools
reinvent_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

    A4.4/5.0

    Scored across 13 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP-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
    • A
      license
      Not graded
      quality
      C
      maintenance
      An 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.
      37
      MIT