MolMCP

Multi-plane MCP for the MolCrafts ecosystem.

Protocol: MCP 2026-07-28 via FastMCP 4.0.0b5 (+ MCP Python SDK v2). Handshake-era clients still work — FastMCP 4 negotiates per connection.

Optional science packages (molvis, molq, molexp, …): if not installed, that plane is omitted from catalogs and client configs (silent). Explicit molmcp serve <plane> still errors with an install hint. This is runtime behavior — not a test skip.

molmcp serve (no plane) starts the molcrafts core and FastMCP-mounts enabled providers into that one process (molvis_open, molq_list_jobs, …). molmcp init <host> writes that one MCP entry and the usage skill. --disable molcrafts errors; --disable molq omits that mount.

Science APIs are never MCP tools. Discover them on molcrafts (packages → open), then call them from agent Python or molvis_exec.

Client config (default: everything)

One standard mcpServers JSON, which every host reads — Claude Code and Cursor natively, Grok alongside its own config.toml.

molmcp init grok                         # skill + composed serve
molmcp init grok --disable molq --disable molexp
molmcp init grok --disable molq --enable molq   # re-enable after a disable
molmcp init claude

Host is required (grok, claude, cursor, codex). JSON is one molcrafts entry running molmcp serve, with --disable flags for omitted mounts. Tool ids look like molcrafts__molvis_open.

In Grok, ~/.grok/config.toml outranks the JSON sources. If an old molmcp entry lives there it still wins — grok inspect shows each server's origin.

Configuration

Settings live in ~/.molmcp/settings.json, edited through the CLI. There are no environment variables.

molmcp config list                                # resolved settings + layers
molmcp config set sources.molpy pkg:molpy         # index a package
molmcp config set indexWorkspace true --project   # index this repo too
molmcp config add excludes vendor
molmcp config remove sources.molpy

A project may carry .molmcp/settings.json (checked in) and .molmcp/settings.local.json (untracked); both layer over the user file. Writes go to the user file unless --project / --local is passed, because a plane server inherits its working directory from whichever client launched it.

What gets indexed. Auto-discovery finds installed MolCrafts distributions. The working directory is not a source unless indexWorkspace says so — it used to be, which meant an unconfigured install indexed whatever it happened to be started next to.

molcrafts.json is no longer picked up from the working directory; pass --config PATH if you keep one.

CLI

uv run molmcp planes              # list planes
uv run molmcp init grok           # skill + MCP config
uv run molmcp config list         # resolved settings
uv run molmcp route "draw dopamine"
uv run molmcp serve               # composed core + mounts
uv run molmcp serve molvis        # debug one plane
uv run molmcp search "Conformer"  # offline index search
uv run molmcp index
uv run molmcp cache               # index size; --prune / --gc / --vacuum to reclaim

Install

uv sync --extra dev
uv run pytest -v

Design rules

1. FastMCP composition — molmcp serve is molcrafts + namespaced mounts.
2. Bare register, namespaced mount — a provider registers open; the stack exposes molvis_open. Debug molmcp serve molvis still shows molvis__open.
3. No science tool mirror — no show_smiles / draw_dopamine; discovery + Python.
4. Providers register via molmcp.providers entry points.
5. No environment switches — configuration is settings and CLI flags, so molmcp config list is the whole truth.

Documentation

Full manual: docs.molcrafts.org/molmcp (sources in docs/):

• Architecture
• Quickstart
• MolVis workbench
• CLI reference

Local sources: docs/concepts/architecture.md, docs/guides/molvis-workbench.md.