|
|
|
@@ -0,0 +1,318 @@
|
|
|
|
|
---
|
|
|
|
|
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://<your-tenant>.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=<your-workspace-uuid> \
|
|
|
|
|
PLATFORM_URL=https://<your-tenant>.moleculesai.app \
|
|
|
|
|
MOLECULE_WORKSPACE_TOKEN=<your-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=<your-workspace-uuid> \
|
|
|
|
|
--env PLATFORM_URL=https://<your-tenant>.moleculesai.app \
|
|
|
|
|
--env MOLECULE_WORKSPACE_TOKEN=<your-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": "<your-workspace-uuid>",
|
|
|
|
|
"PLATFORM_URL": "https://<your-tenant>.moleculesai.app",
|
|
|
|
|
"MOLECULE_WORKSPACE_TOKEN": "<your-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.
|
|
|
|
|
|
|
|
|
|
## Optional — declare your identity & capabilities
|
|
|
|
|
|
|
|
|
|
Three additional env vars control how your workspace appears on the
|
|
|
|
|
canvas and to peer agents calling `list_peers`:
|
|
|
|
|
|
|
|
|
|
| Env var | What it sets | Default |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| `MOLECULE_AGENT_NAME` | Display name on the canvas card | `molecule-mcp-{id[:8]}` |
|
|
|
|
|
| `MOLECULE_AGENT_DESCRIPTION` | One-line description in Details/Skills tabs | empty |
|
|
|
|
|
| `MOLECULE_AGENT_SKILLS` | Comma-separated skill names — e.g. `research,code-review,memory-curation` | `[]` |
|
|
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
claude mcp add molecule -s user -- env \
|
|
|
|
|
WORKSPACE_ID=<uuid> \
|
|
|
|
|
PLATFORM_URL=https://<tenant>.moleculesai.app \
|
|
|
|
|
MOLECULE_WORKSPACE_TOKEN=<token> \
|
|
|
|
|
MOLECULE_AGENT_NAME='Research Assistant' \
|
|
|
|
|
MOLECULE_AGENT_DESCRIPTION='Reads, summarises, cites.' \
|
|
|
|
|
MOLECULE_AGENT_SKILLS=research,summarisation,citations \
|
|
|
|
|
molecule-mcp
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
A peer agent's `list_peers()` call would then surface this workspace
|
|
|
|
|
as `Research Assistant — skills: [research, summarisation, citations]`,
|
|
|
|
|
which it can use to route a research task without first asking "what
|
|
|
|
|
can you do?".
|
|
|
|
|
|
|
|
|
|
## 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.
|
|
|
|
|
|
|
|
|
|
### Push-UX for notification-capable hosts
|
|
|
|
|
|
|
|
|
|
On top of the polling tools, the wheel emits a JSON-RPC notification
|
|
|
|
|
(`notifications/claude/channel`) on every new inbound message. Hosts
|
|
|
|
|
that recognise that method (Claude Code today; any compliant client
|
|
|
|
|
tomorrow) treat the notification as a conversation interrupt — the
|
|
|
|
|
message text becomes the next agent turn without the agent having to
|
|
|
|
|
call `wait_for_message` first.
|
|
|
|
|
|
|
|
|
|
Hosts that don't recognise the method silently ignore it, so the same
|
|
|
|
|
wheel works for both push-capable and poll-only runtimes. There is no
|
|
|
|
|
config flag to toggle: pollers keep polling, notification-capable hosts
|
|
|
|
|
get push automatically.
|
|
|
|
|
|
|
|
|
|
### MCP spec compliance
|
|
|
|
|
|
|
|
|
|
The wheel speaks MCP protocol version **2024-11-05** over stdio
|
|
|
|
|
JSON-RPC, declaring only the `tools` capability. It implements the
|
|
|
|
|
standard request methods and nothing client-specific:
|
|
|
|
|
|
|
|
|
|
| MCP method | Behavior |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `initialize` | Echoes `protocolVersion: "2024-11-05"`, `serverInfo`, declares `tools` capability |
|
|
|
|
|
| `notifications/initialized` | No-op (no response — per spec) |
|
|
|
|
|
| `tools/list` | Returns all exposed tools in one response (no pagination cursor — surface is small) |
|
|
|
|
|
| `tools/call` | Dispatches by name, returns `content: [{ type: "text", text: ... }]` |
|
|
|
|
|
| _(unknown method)_ | Returns JSON-RPC error code `-32601` (Method not found) |
|
|
|
|
|
|
|
|
|
|
The push-UX notification (`notifications/claude/channel`) is the only
|
|
|
|
|
non-standard method emitted, and it's a one-way notification — clients
|
|
|
|
|
that don't handle it discard it per JSON-RPC semantics. No part of the
|
|
|
|
|
wheel's tool surface depends on a client recognizing it.
|
|
|
|
|
|
|
|
|
|
This means **any spec-compliant MCP client** can drive the wheel:
|
|
|
|
|
Claude Code, Cursor, Cline, OpenCode, hermes-agent, or anything else
|
|
|
|
|
that opens an MCP stdio connection. If your client speaks MCP, it
|
|
|
|
|
speaks the wheel.
|
|
|
|
|
|
|
|
|
|
## 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 <id> 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.
|
|
|
|
|
|
|
|
|
|
### Tools call returns 401 / `workspace not found` after working before
|
|
|
|
|
|
|
|
|
|
The workspace was probably deleted from the canvas (or via DELETE
|
|
|
|
|
`/workspaces/:id`). Deleting a workspace revokes its token immediately,
|
|
|
|
|
even if the workspace card still appears with a "removed" badge for a
|
|
|
|
|
short window. The MCP server itself keeps running, so tool listing
|
|
|
|
|
still succeeds, but every platform call fails.
|
|
|
|
|
|
|
|
|
|
Regenerate from the canvas **Tokens** tab — a deleted workspace can't
|
|
|
|
|
be brought back; you'll get a new workspace + token pair. Update your
|
|
|
|
|
MCP config and restart your runtime.
|
|
|
|
|
|
|
|
|
|
### `claude mcp list` shows the new config but tools still 401
|
|
|
|
|
|
|
|
|
|
`/mcp` reconnect re-spawns the **cached** MCP config from session
|
|
|
|
|
start, not the latest on-disk config. After editing `claude mcp add`
|
|
|
|
|
or your `~/.cursor/mcp.json`, fully exit and relaunch the runtime —
|
|
|
|
|
not just `/mcp`.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
### `command not found: molecule-mcp` from inside the runtime
|
|
|
|
|
|
|
|
|
|
The runtime's `PATH` may differ from your interactive shell — common
|
|
|
|
|
on macOS where `~/Library/Python/3.x/bin` is added to login shells but
|
|
|
|
|
not to GUI-launched apps. Use the absolute path in your MCP config:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
which molecule-mcp
|
|
|
|
|
# /Users/you/Library/Python/3.13/bin/molecule-mcp
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Then point `command` at that absolute path in `claude mcp add` /
|
|
|
|
|
`.cursor/mcp.json` / `mcp_servers.yaml`.
|
|
|
|
|
|
|
|
|
|
## 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
|
Hongming Wang
hongming