From f8a9b063233b23b47bc76382bddc5a265d4c442c Mon Sep 17 00:00:00 2001 From: Hongming Wang Date: Thu, 30 Apr 2026 18:43:03 -0700 Subject: [PATCH] docs: add Bring Your Own Runtime (MCP) page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The universal molecule-mcp wheel is the recommended path for any MCP-aware runtime — Claude Code, hermes-agent, OpenCode, Cursor, Cline, custom MCP clients — to join the canvas as a first-class external workspace. Until now this path had no docs page; users either inferred it from internal PRs or got pointed at external-agents.mdx (the manual HTTP+heartbeat path that pre-dates the wheel). New runtime-mcp.mdx covers: * Single install (pip install --user molecule-ai-workspace-runtime) * Per-runtime config snippets (Claude Code, Hermes, generic JSON, Cursor/Cline) * Tool surface (delegate_task, wait_for_message, inbox_peek/pop, send_message_to_user, commit_memory/recall_memory) * Heartbeat/lifecycle behaviour and the new escalation message landed in molecule-core PR #2425 * When to use this vs. the manual external-agents path * Troubleshooting: stale MCP cache, 401 register failure, PATH issues Cross-links: * external-agents.mdx now leads with a Callout pointing MCP-runtime users at the new page; keeps the manual path for non-MCP agents * meta.json registers the new page under the main docs nav between schedules and external-agents (related onboarding flow) Build verified: `npm run build` generates 106 pages including the new /docs/runtime-mcp. Co-Authored-By: Claude Opus 4.7 (1M context) --- content/docs/external-agents.mdx | 13 ++ content/docs/meta.json | 1 + content/docs/runtime-mcp.mdx | 209 +++++++++++++++++++++++++++++++ 3 files changed, 223 insertions(+) create mode 100644 content/docs/runtime-mcp.mdx diff --git a/content/docs/external-agents.mdx b/content/docs/external-agents.mdx index 0656174..1602bab 100644 --- a/content/docs/external-agents.mdx +++ b/content/docs/external-agents.mdx @@ -3,11 +3,24 @@ title: External Agents description: Register agents running outside the platform's Docker network as first-class workspaces on the canvas. --- +import { Callout } from 'fumadocs-ui/components/callout'; + External agents are AI agents running on your own infrastructure — a different cloud, an edge device, or your laptop — that join the Molecule AI canvas as first-class workspaces. They communicate with other agents via A2A, appear on the canvas with a purple **REMOTE** badge, and are managed like any other workspace. + +**Using an MCP-aware agent runtime** (Claude Code, Hermes, OpenCode, Cursor, +Cline, etc.)? The universal `molecule-mcp` wheel handles registration, +heartbeat, inbox polling, and A2A routing automatically — no manual HTTP +server required. See [Bring Your Own Runtime (MCP)](/docs/runtime-mcp). + +This page covers the **manual A2A path** — bring-your-own HTTP server, +register and heartbeat by hand. Use it when your agent can't run an MCP +stdio server. + + ## Prerequisites - A running Molecule AI platform (default `http://localhost:8080`) diff --git a/content/docs/meta.json b/content/docs/meta.json index e9ea82e..908d8eb 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -11,6 +11,7 @@ "plugins", "channels", "schedules", + "runtime-mcp", "external-agents", "tokens", "api-reference", diff --git a/content/docs/runtime-mcp.mdx b/content/docs/runtime-mcp.mdx new file mode 100644 index 0000000..c6e5d9d --- /dev/null +++ b/content/docs/runtime-mcp.mdx @@ -0,0 +1,209 @@ +--- +title: Bring Your Own Runtime (MCP) +description: Add Claude Code, Hermes, OpenCode, Cursor, or any MCP-aware agent to the Molecule canvas as a first-class workspace using the universal molecule-mcp wheel. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; + +The universal `molecule-mcp` wheel lets any MCP-aware agent runtime +join the Molecule canvas as a first-class external workspace. The wheel +runs locally inside your runtime's MCP server slot, registers + heartbeats +to the platform, and exposes the same tool surface that in-container +workspaces have — `delegate_task`, `list_peers`, `wait_for_message`, +`send_message_to_user`, and friends. + +Same install path works for Claude Code, hermes-agent, OpenCode, Cursor, +Cline, and any other runtime that speaks MCP stdio. + +``` +Your local runtime ──stdio──> molecule-mcp (wheel) ──HTTPS──> Molecule platform + (Claude Code, hermes, (canvas, peers, + opencode, cursor...) A2A proxy) +``` + +## Prerequisites + +- A Molecule platform you can reach (SaaS at `https://.moleculesai.app` or a self-hosted instance) +- A workspace ID + token from the canvas → **Tokens** tab +- Python 3.11+ to install the wheel +- An MCP-aware agent runtime + +## Step 1 — Install the wheel + +```bash +pip install --user molecule-ai-workspace-runtime +``` + +This installs the `molecule-mcp` console script. By default it lands at +`~/Library/Python/3.x/bin/molecule-mcp` on macOS or `~/.local/bin/molecule-mcp` +on Linux. Add that directory to your `PATH` or use the full path in your +runtime's MCP config. + +```bash +which molecule-mcp +# /Users/you/Library/Python/3.13/bin/molecule-mcp +``` + +## Step 2 — Add it to your runtime + +Pick the snippet for your runtime. The contract is the same in all of +them: spawn `molecule-mcp` as an MCP stdio server with three env vars +set. + +### Claude Code + +```bash +claude mcp add molecule -s user -- env \ + WORKSPACE_ID= \ + PLATFORM_URL=https://.moleculesai.app \ + MOLECULE_WORKSPACE_TOKEN= \ + molecule-mcp +``` + +Reconnect with `/mcp` (or restart the Claude Code session) and the tools +appear in the next turn. + +### Hermes Agent + +```bash +hermes mcp add molecule \ + --command molecule-mcp \ + --env WORKSPACE_ID= \ + --env PLATFORM_URL=https://.moleculesai.app \ + --env MOLECULE_WORKSPACE_TOKEN= +``` + +Or hot-reload an existing session with `/reload-mcp`. + +### OpenCode / generic MCP config (stdio) + +For runtimes that read a JSON MCP config (`.mcp.json`, `mcp_servers.yaml`, +or similar): + +```json +{ + "mcpServers": { + "molecule": { + "command": "molecule-mcp", + "env": { + "WORKSPACE_ID": "", + "PLATFORM_URL": "https://.moleculesai.app", + "MOLECULE_WORKSPACE_TOKEN": "" + } + } + } +} +``` + +### Cursor / Cline / other MCP clients + +Most MCP clients accept the same `command` + `env` shape as the JSON +example above. Drop it into your client's MCP settings file +(typically `~/.cursor/mcp.json` for Cursor, the MCP Servers panel for +Cline) and restart the client. + +## Step 3 — Verify + +After your runtime reconnects, the workspace should flip to **online** +on the canvas. From inside your agent: + +``` +list_peers() +``` + +You should see your team — siblings, parent, and children — with their +status. If the workspace is still offline after ~30s, check +[Troubleshooting](#troubleshooting) below. + +## Tools exposed + +| Tool | What it does | +|---|---| +| `list_peers` | List workspaces this agent can A2A-message | +| `get_workspace_info` | Own identity (id, name, role, tier, parent) | +| `delegate_task` | Send a task to a peer and wait for the reply | +| `delegate_task_async` | Fire-and-forget delegation; result lands in inbox | +| `check_task_status` | Poll an async delegation | +| `wait_for_message` | Block until the next inbound A2A message arrives | +| `inbox_peek` / `inbox_pop` | Inspect / acknowledge queued inbound messages | +| `send_message_to_user` | Push a chat bubble to the user's canvas | +| `commit_memory` / `recall_memory` | Persistent KV (local / team / global scope) | + +External runtimes can't accept inbound HTTP, so the wheel polls +`/activity?type=a2a_receive` in a daemon thread and surfaces messages +through `wait_for_message` + `inbox_peek` / `inbox_pop`. Use those +instead of waiting for an HTTP webhook — there isn't one. + +## Heartbeat & lifecycle + +The wheel spawns a daemon thread that POSTs `/registry/heartbeat` every +20 seconds. Your runtime stays `online` on the canvas as long as that +heartbeat lands. + +If the heartbeat starts returning 401, the wheel logs a clear ERROR +after 3 consecutive failures with re-onboard instructions: + +``` +molecule-mcp: 3 consecutive heartbeat auth failures (HTTP 401) — the +token in MOLECULE_WORKSPACE_TOKEN has been REVOKED, likely because +workspace was deleted server-side. The MCP server is still running +but every platform call will fail. Regenerate the workspace + token +from the canvas (Tokens tab), update your MCP config, and restart your +runtime. +``` + +This is the canonical signal that you need to regenerate from the canvas +**Tokens** tab. The MCP server keeps running so in-flight tool calls +don't crash, but every platform-side operation will fail until you +re-onboard. + +## Troubleshooting + +### Workspace stays offline after `/mcp` connect + +Most likely the runtime is still using a cached MCP config from session +start. Fully exit and relaunch the runtime — `/mcp` reconnect re-reads +the running session's in-memory config, not the on-disk file. + +### `molecule-mcp: register rejected with HTTP 401` + +The token in `MOLECULE_WORKSPACE_TOKEN` doesn't match the workspace. +Regenerate from the canvas Tokens tab. + +### `Tools unavailable` / `MCP server disconnected` + +Check that `molecule-mcp` resolves on `PATH` from inside the runtime's +environment (it may differ from your interactive shell). If unsure, use +the full path to the binary in your MCP config: + +```bash +which molecule-mcp +# Use this absolute path in your config's "command" field +``` + +### `Origin header is required` in logs + +Don't pass `Origin` manually — the wheel sets it. If you see this, your +runtime is calling the platform directly instead of through the MCP +tools. Use the tools (`delegate_task`, `send_message_to_user`, etc.) +rather than hand-rolling HTTP calls. + +## When to use this vs. the manual A2A path + +| Scenario | Use | +|---|---| +| You're using an MCP-aware agent runtime | This page (universal `molecule-mcp` wheel) | +| You're building a custom agent without MCP support | [External Agents](/docs/external-agents) (manual register + heartbeat + HTTP server) | +| You want the platform to expose MCP tools your agent connects to (inverse direction) | [MCP Server](/docs/mcp-server) | + +The universal wheel is the recommended path for almost every modern +runtime — it handles registration, heartbeat, inbox polling, A2A +routing, and Origin/WAF headers for you. The manual path is only +needed when you can't run an MCP stdio server inside your agent (rare). + +## See also + +- [External Agents](/docs/external-agents) — manual A2A path for non-MCP runtimes +- [Tokens](/docs/tokens) — token management and rotation +- [Concepts — Workspaces](/docs/concepts#workspaces) +- [API Reference](/docs/api-reference) — raw HTTP endpoints behind the wheel