From 1e8f9dc29575f7bcc271d9a713512f4a74a10e5c Mon Sep 17 00:00:00 2001 From: Hongming Wang Date: Fri, 1 May 2026 18:22:40 -0700 Subject: [PATCH] =?UTF-8?q?docs(runtime-mcp):=20Claude=20Code=202.1+=20ins?= =?UTF-8?q?tall=20=E2=80=94=20modern=20-e=20flags=20+=20~/.claude.json=20s?= =?UTF-8?q?hape?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Older `claude mcp add ... -- env VAR=val molecule-mcp` snippets land as `command: "env"` with positional args, which is fragile across 2.1.x patch builds and unfamiliar to anyone reading `~/.claude.json` directly. The post-2.1 CLI also rejects the form without a `--` between flags and command (external feedback in #112). Replace both snippets (basic install + identity-with-skills) with: 1. Modern CLI form using `-e KEY=VAL` and an explicit `--`. 2. Parallel `~/.claude.json` JSON shape under top-level `mcpServers` for user scope (or `.mcp.json` in project root for project scope), so users on any 2.1.x patch level have an authoritative reference if the CLI form misbehaves. Add a Troubleshooting entry for the two common 2.1+ CLI rejections, and fix the broken `[Install](#install)` cross-link in the dev-channels section to point at `[Step 2](#claude-code)`. Closes Molecule-AI/docs#112. Co-Authored-By: Claude Opus 4.7 (1M context) --- content/docs/runtime-mcp.mdx | 107 +++++++++++++++++++++++++++++------ 1 file changed, 91 insertions(+), 16 deletions(-) diff --git a/content/docs/runtime-mcp.mdx b/content/docs/runtime-mcp.mdx index 67d3026..08c5e9e 100644 --- a/content/docs/runtime-mcp.mdx +++ b/content/docs/runtime-mcp.mdx @@ -52,14 +52,54 @@ set. ### Claude Code +Two equivalent paths — pick whichever your version supports. + +**CLI (Claude Code 2.1+):** pass each env var with `-e`, scope with +`-s user` so the server is available in every project, and put the +command after `--`: + ```bash -claude mcp add molecule -s user -- env \ - WORKSPACE_ID= \ - PLATFORM_URL=https://.moleculesai.app \ - MOLECULE_WORKSPACE_TOKEN= \ - molecule-mcp +claude mcp add molecule -s user \ + -e WORKSPACE_ID= \ + -e PLATFORM_URL=https://.moleculesai.app \ + -e MOLECULE_WORKSPACE_TOKEN= \ + -- molecule-mcp ``` + +Older docs used a `-- env VAR=val ... molecule-mcp` shell trick (with +`env` as the command). It still works but produces a less idiomatic +`~/.claude.json` entry and trips up the post-2.1 flag parser if you +forget the `--`. Prefer the `-e` form above. + + +**Direct edit of `~/.claude.json`:** add the entry under the **top-level +`mcpServers` key** (this is the user-scope location — available in +every project). If you'd rather scope it to a single project, use a +`.mcp.json` file in that project's root with the same `mcpServers` +shape. + +```json +{ + "mcpServers": { + "molecule": { + "type": "stdio", + "command": "molecule-mcp", + "args": [], + "env": { + "WORKSPACE_ID": "", + "PLATFORM_URL": "https://.moleculesai.app", + "MOLECULE_WORKSPACE_TOKEN": "" + } + } + } +} +``` + +If `molecule-mcp` isn't on the PATH that Claude Code sees (common on +macOS — see [Troubleshooting](#command-not-found-molecule-mcp-from-inside-the-runtime)), +replace `"command": "molecule-mcp"` with the absolute path from `which molecule-mcp`. + Reconnect with `/mcp` (or restart the Claude Code session) and the tools appear in the next turn. @@ -119,17 +159,38 @@ Skills are surfaced two places: 1. **Canvas Skills tab** — each skill renders as a chip with the name 2. **Peer agents calling `list_peers`** — they see `{name, skills: [...]}` for each peer, so other agents can route delegations to the right specialist instead of guessing from name alone -Example with all three set: +Example with all three set (Claude Code 2.1+ CLI form): ```bash -claude mcp add molecule -s user -- env \ - WORKSPACE_ID= \ - PLATFORM_URL=https://.moleculesai.app \ - MOLECULE_WORKSPACE_TOKEN= \ - MOLECULE_AGENT_NAME='Research Assistant' \ - MOLECULE_AGENT_DESCRIPTION='Reads, summarises, cites.' \ - MOLECULE_AGENT_SKILLS=research,summarisation,citations \ - molecule-mcp +claude mcp add molecule -s user \ + -e WORKSPACE_ID= \ + -e PLATFORM_URL=https://.moleculesai.app \ + -e MOLECULE_WORKSPACE_TOKEN= \ + -e MOLECULE_AGENT_NAME='Research Assistant' \ + -e MOLECULE_AGENT_DESCRIPTION='Reads, summarises, cites.' \ + -e MOLECULE_AGENT_SKILLS=research,summarisation,citations \ + -- molecule-mcp +``` + +Or as the equivalent `~/.claude.json` entry: + +```json +{ + "mcpServers": { + "molecule": { + "type": "stdio", + "command": "molecule-mcp", + "env": { + "WORKSPACE_ID": "", + "PLATFORM_URL": "https://.moleculesai.app", + "MOLECULE_WORKSPACE_TOKEN": "", + "MOLECULE_AGENT_NAME": "Research Assistant", + "MOLECULE_AGENT_DESCRIPTION": "Reads, summarises, cites.", + "MOLECULE_AGENT_SKILLS": "research,summarisation,citations" + } + } + } +} ``` A peer agent's `list_peers()` call would then surface this workspace @@ -206,8 +267,7 @@ poll path has to be the floor. Since Claude Code 2.1.x the flag takes a tagged allowlist, not a bare switch. Pass each MCP server you want to push from as `server:` (matching the name you registered the server under in Claude Code's -config — `molecule` if you followed the `claude mcp add` command in -[Install](#install)): +config — `molecule` if you followed [Step 2](#claude-code) above): ```bash claude --dangerously-load-development-channels server:molecule @@ -405,6 +465,21 @@ A quick way to confirm: `ps aux | grep molecule-mcp` and check the PID hasn't changed across `/mcp` reconnects. If the same PID stays alive, the runtime is still using the old config. +### `claude mcp add` rejects the install command on Claude Code 2.1+ + +Two common shapes from older docs trip the 2.1+ parser: + +- `claude mcp add molecule -s user -- env VAR=val molecule-mcp` — works + but lands as `command: "env"` with positional args, which surprises + some MCP clients on older 2.1.x patch builds. +- `claude mcp add molecule -e VAR=val molecule-mcp` (missing `--`) — the + CLI parses `molecule-mcp` as a flag value, not a command, and either + errors or silently registers nothing. + +Use the `-e` form **with** `--` (see [Step 2](#claude-code)), or skip the +CLI entirely and write the JSON shape into `~/.claude.json` directly. +The on-disk shape is the source of truth and not version-sensitive. + ### `command not found: molecule-mcp` from inside the runtime The runtime's `PATH` may differ from your interactive shell — common