Compare commits
21 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 documentation-specialist
|
a52ed96143 | ||
|
documentation-specialist
|
d05d92b666 | ||
 claude-ceo-assistant
|
46615a07cf | ||
|
claude-ceo-assistant
|
6d08619871 | ||
|
Hongming Wang
|
75d85a6ae2 | ||
|
Hongming Wang
|
f1ed8784ff | ||
|
Hongming Wang
|
78665e35ed | ||
|
Hongming Wang
|
798294b62a | ||
|
Hongming Wang
|
7df9bb6631 | ||
|
Hongming Wang
|
6a99eb0896 | ||
 hongming
|
12c35656f4 | ||
|
Hongming Wang
|
fa6db57daf | ||
|
Hongming Wang
|
00dfb0a5fc | ||
|
Hongming Wang
|
f8a9b06323 | ||
|
Hongming Wang
|
32e7de04e3 | ||
|
Hongming Wang
|
5624261de8 | ||
|
hongming
|
988063e537 | ||
|
rabbitblood
|
543906e4e5 | ||
|
rabbitblood
|
a29db81b92 | ||
|
rabbitblood
|
017f846ce2 | ||
|
rabbitblood
|
fe49ed01d9 |
@@ -0,0 +1,22 @@
|
||||
name: Secret scan
|
||||
|
||||
# Calls the canonical reusable workflow in molecule-core. Defense
|
||||
# against the #2090-class leak (a hosted-agent commit slipping a
|
||||
# credential-shaped string into a PR). Pattern set lives in
|
||||
# molecule-core so we don't maintain a parallel copy here.
|
||||
#
|
||||
# Pinned to @staging because that's the active default branch on the
|
||||
# upstream repo (main lags behind via the staging-promotion workflow).
|
||||
# Updates ride along automatically as the upstream regex set evolves.
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [opened, synchronize, reopened]
|
||||
push:
|
||||
branches: [main, staging]
|
||||
merge_group:
|
||||
types: [checks_requested]
|
||||
|
||||
jobs:
|
||||
secret-scan:
|
||||
uses: Molecule-AI/molecule-core/.github/workflows/secret-scan.yml@staging
|
||||
+2
-2
@@ -18,10 +18,10 @@ export default function HomePage() {
|
||||
Read the docs
|
||||
</Link>
|
||||
<Link
|
||||
href="https://github.com/Molecule-AI/molecule-monorepo"
|
||||
href="https://git.moleculesai.app/molecule-ai/molecule-core"
|
||||
className="rounded-md border border-fd-border px-5 py-2.5 text-sm font-medium transition-colors hover:bg-fd-muted"
|
||||
>
|
||||
View on GitHub
|
||||
View on Gitea
|
||||
</Link>
|
||||
</div>
|
||||
</main>
|
||||
|
||||
@@ -138,7 +138,7 @@ These controls complement the platform-level secret redaction described in the [
|
||||
|
||||
**Stack:** Go / Bubbletea + Lipgloss
|
||||
|
||||
A terminal UI dashboard for real-time workspace monitoring, event log streaming, health overview, and delete/filter operations. Reads `MOLECLI_URL` (default `http://localhost:8080`) to locate the platform. Now published as a standalone repo at `github.com/Molecule-AI/molecule-cli`.
|
||||
A terminal UI dashboard for real-time workspace monitoring, event log streaming, health overview, and delete/filter operations. Reads `MOLECLI_URL` (default `http://localhost:8080`) to locate the platform. Now published as a standalone repo at `git.moleculesai.app/molecule-ai/molecule-cli`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ title: "Molecule AI — Comprehensive Technical Documentation"
|
||||
# Molecule AI — Comprehensive Technical Documentation
|
||||
|
||||
> Definitive technical reference for the Molecule AI Agent Team platform.
|
||||
> Based on a full non-invasive scan of the [molecule-monorepo](https://github.com/Molecule-AI/molecule-monorepo) repository.
|
||||
> Based on a full non-invasive scan of the [molecule-core](https://git.moleculesai.app/molecule-ai/molecule-core) repository (formerly `molecule-monorepo`, renamed during the post-2026-05-06 GitHub-org-suspension recovery).
|
||||
|
||||
---
|
||||
|
||||
@@ -1153,11 +1153,11 @@ Molecule AI's workspace abstraction is **runtime-agnostic by design**. A workspa
|
||||
|
||||
## Links
|
||||
|
||||
- **GitHub**: https://github.com/Molecule-AI/molecule-monorepo
|
||||
- **Architecture Docs**: https://github.com/Molecule-AI/molecule-monorepo/tree/main/docs/architecture
|
||||
- **API Protocol**: https://github.com/Molecule-AI/molecule-monorepo/tree/main/docs/api-protocol
|
||||
- **Agent Runtime**: https://github.com/Molecule-AI/molecule-monorepo/tree/main/docs/agent-runtime
|
||||
- **Product Docs**: https://github.com/Molecule-AI/molecule-monorepo/tree/main/docs/product
|
||||
- **Gitea**: https://git.moleculesai.app/molecule-ai/molecule-core
|
||||
- **Architecture Docs**: https://git.moleculesai.app/molecule-ai/molecule-core/src/branch/main/docs/architecture
|
||||
- **API Protocol**: https://git.moleculesai.app/molecule-ai/molecule-core/src/branch/main/docs/api-protocol
|
||||
- **Agent Runtime**: https://git.moleculesai.app/molecule-ai/molecule-core/src/branch/main/docs/agent-runtime
|
||||
- **Product Docs**: https://git.moleculesai.app/molecule-ai/molecule-core/src/branch/main/docs/product
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
<Callout type="info">
|
||||
**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.
|
||||
</Callout>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A running Molecule AI platform (default `http://localhost:8080`)
|
||||
@@ -231,6 +244,24 @@ create (POST /workspaces) → online (register) → offline (heartbeat expires)
|
||||
- No auto-restart (agent manages its own process)
|
||||
- Paused external workspaces skip heartbeat monitoring
|
||||
|
||||
### `removed` status — 410 Gone (#2429)
|
||||
|
||||
Once a workspace transitions to `removed`:
|
||||
|
||||
- **Tokens are revoked immediately**, but the row stays in the DB for audit-trail purposes
|
||||
- `GET /workspaces/:id` returns **410 Gone** with `{error: "workspace removed", id, removed_at, hint}` so callers fail fast at startup instead of after ~60s of heartbeat 401s
|
||||
- `DELETE /workspaces/:id` is the canonical removal trigger
|
||||
- Audit / admin tooling that intentionally wants the legacy 200 + body shape opts in via `GET /workspaces/:id?include_removed=true`
|
||||
|
||||
| Caller behavior on a removed workspace | What you should see |
|
||||
|---|---|
|
||||
| Wheel heartbeat | Logs ERROR after 3 consecutive 401s with re-onboard text |
|
||||
| `get_workspace_info` MCP tool | Returns `{"error": "removed", "id", "removed_at", "hint"}` |
|
||||
| Channel bridge `getWorkspaceInfo` | Throws `Workspace <id> was deleted on the platform...` |
|
||||
| Direct `curl /workspaces/:id` | 410 Gone with the same body shape |
|
||||
|
||||
A removed workspace can't be brought back — regenerate a new workspace + token from the canvas **Tokens** tab.
|
||||
|
||||
## Security
|
||||
|
||||
- Bearer token required on all authenticated endpoints
|
||||
|
||||
@@ -220,7 +220,7 @@ Push mode (this guide) works today but requires an inbound-reachable URL — whi
|
||||
|
||||
Your agent makes only outbound HTTPS calls to the platform, pulling messages from an inbox queue and posting replies back. Works behind any NAT/firewall, tolerates offline laptops, no tunnel needed.
|
||||
|
||||
See the [design doc](https://github.com/Molecule-AI/internal/blob/main/product/external-workspaces-polling.md) (internal) and [implementation tracking issue](https://github.com/Molecule-AI/molecule-core/issues?q=polling+mode) once opened.
|
||||
See the [design doc](https://git.moleculesai.app/molecule-ai/internal/src/branch/main/product/external-workspaces-polling.md) (internal) and the implementation tracking issue (search `polling+mode` on the [molecule-core issue tracker](https://git.moleculesai.app/molecule-ai/molecule-core/issues)).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -148,5 +148,5 @@ The agent appears on the canvas with a **purple REMOTE badge** within seconds. F
|
||||
## Next Steps
|
||||
|
||||
- **[External Agent Registration Guide →](/docs/guides/external-agent-registration)** — full endpoint reference, Python + Node.js examples, troubleshooting
|
||||
- **[molecule-sdk-python →](https://github.com/Molecule-AI/molecule-sdk-python)** — SDK source, `RemoteAgentClient` API docs
|
||||
- **[SDK Examples →](https://github.com/Molecule-AI/molecule-sdk-python/tree/main/examples/remote-agent)** — `run.py` demo script, annotated walkthrough
|
||||
- **[molecule-sdk-python →](https://git.moleculesai.app/molecule-ai/molecule-sdk-python)** — SDK source, `RemoteAgentClient` API docs
|
||||
- **[SDK Examples →](https://git.moleculesai.app/molecule-ai/molecule-sdk-python/src/branch/main/examples/remote-agent)** — `run.py` demo script, annotated walkthrough
|
||||
|
||||
@@ -65,7 +65,7 @@ molecule skills install arxiv-research --from community
|
||||
|
||||
Community skills are reviewed by the Molecule AI team before being
|
||||
listed. Submit a skill for review by opening a PR against
|
||||
[`molecule-ai/skills`](https://github.com/Molecule-AI/skills).
|
||||
`molecule-ai/skills` (repo location TBD post-2026-05-06 GitHub-org-suspension; check the [internal issue tracker](https://git.moleculesai.app/molecule-ai/internal/issues) for the canonical submission path).
|
||||
|
||||
## Installing via config.yaml
|
||||
|
||||
@@ -171,7 +171,7 @@ molecule skills bundle my-custom-skill --output ./org-templates/my-role/
|
||||
```
|
||||
|
||||
**Publishing to the community:** Open a PR against
|
||||
[`molecule-ai/skills`](https://github.com/Molecule-AI/skills) with a
|
||||
`molecule-ai/skills` (repo location TBD post-2026-05-06 GitHub-org-suspension; check the [internal issue tracker](https://git.moleculesai.app/molecule-ai/internal/issues) for the canonical submission path) with a
|
||||
complete skill package. Community skills are reviewed for security and
|
||||
correctness before listing.
|
||||
|
||||
|
||||
@@ -88,7 +88,7 @@ Commit `d513a0ced549ef2be8903a7b4794256110ba1805` on staging (merged to main via
|
||||
|---|------------|-------|--------|
|
||||
| 1 | ANTHROPIC_AUTH_TOKEN | `sk-cp-lHt-QFSyZwZxeo...KVw` | ⚠️ Revoked or inactive (404 on API call) |
|
||||
| 2 | GITHUB_TOKEN | `github_pat_11BPRRWQI0m...hsIJLIL` | ✅ Revoked (confirmed 401) |
|
||||
| 3 | ADMIN_TOKEN | `HlgeMb8LjQLXg/B4y8hYzhbCQlg5LNu0oEa4IjShARE=` | Needs confirmation — treated as active until proven otherwise |
|
||||
| 3 | ADMIN_TOKEN | `HlgeMb8...ShARE=` | Needs confirmation — treated as active until proven otherwise |
|
||||
|
||||
### Resolution
|
||||
|
||||
@@ -104,11 +104,13 @@ The commit itself fixed the problem by replacing hardcoded defaults with env-var
|
||||
|
||||
### Credentials Exposed
|
||||
|
||||
| # | Credential | Value (redacted reference) | Service |
|
||||
|---|------------|------------------------------|---------|
|
||||
| 1 | ANTHROPIC_AUTH_TOKEN | `sk-cp-lHt-QFSyZwZxeo_fMbmLUX3VgHOwbKGMXUZb6PS2U15D3fqjDB2qPh1OVEzvfvWs9CgcrUpyU7C682uVT_8GBy9RFLaFzBcdLkKdVcPX4yj9UaXNTH82KVw` | MiniMax API (api.minimax.io/anthropic) |
|
||||
| 2 | GITHUB_TOKEN | `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` | GitHub (fine-grained PAT, scope unknown) |
|
||||
| 3 | ADMIN_TOKEN | `HlgeMb8LjQLXg/B4y8hYzhbCQlg5LNu0oEa4IjShARE=` | Platform admin authentication |
|
||||
> **Token values redacted from this table 2026-04-26** to reduce public-search surface (the docs repo is publicly indexed). Short-suffix references match the convention in the Blast Radius table below (lines 134-137). Full values remain in `molecule-core` git history per the F1088 closure decision (no BFG scrub).
|
||||
|
||||
| # | Credential | Value (short suffix) | Service |
|
||||
|---|------------|----------------------|---------|
|
||||
| 1 | ANTHROPIC_AUTH_TOKEN | `sk-cp-...KVw` | MiniMax API (api.minimax.io/anthropic) |
|
||||
| 2 | GITHUB_TOKEN | `github_pat_...hsIJLIL` | GitHub (fine-grained PAT, scope unknown) |
|
||||
| 3 | ADMIN_TOKEN | `HlgeMb8...ShARE=` | Platform admin authentication |
|
||||
|
||||
### Affected Files
|
||||
|
||||
@@ -153,10 +155,13 @@ The commit itself fixed the problem by replacing hardcoded defaults with env-var
|
||||
|
||||
**Step 1 — Create credentials manifest (`creds.txt`) [NOT NEEDED]:**
|
||||
```
|
||||
HlgeMb8LjQLXg/B4y8hYzhbCQlg5LNu0oEa4IjShARE=
|
||||
sk-cp-lHt-QFSyZwZxeo_fMbmLUX3VgHOwbKGMXUZb6PS2U15D3fqjDB2qPh1OVEzvfvWs9CgcrUpyU7C682uVT_8GBy9RFLaFzBcdLkKdVcPX4yj9UaXNTH82KVw
|
||||
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
|
||||
<ADMIN_TOKEN value>
|
||||
<MiniMax sk-cp-... value>
|
||||
<GitHub fine-grained PAT value>
|
||||
```
|
||||
Full token values redacted from this doc 2026-04-26 (see note in the
|
||||
Credentials Exposed table above). Pull from the Core-Security incident
|
||||
ticket if a future revival of this BFG procedure is needed.
|
||||
|
||||
**Step 2 — Clean origin/main:**
|
||||
```bash
|
||||
|
||||
@@ -11,6 +11,7 @@
|
||||
"plugins",
|
||||
"channels",
|
||||
"schedules",
|
||||
"runtime-mcp",
|
||||
"external-agents",
|
||||
"tokens",
|
||||
"api-reference",
|
||||
|
||||
@@ -11,7 +11,7 @@ Get a Molecule AI workspace running in under five minutes.
|
||||
## 1. Install Molecule AI
|
||||
|
||||
```bash
|
||||
git clone https://github.com/Molecule-AI/molecule-core.git
|
||||
git clone https://git.moleculesai.app/molecule-ai/molecule-core.git
|
||||
cd molecule-core
|
||||
docker compose up -d
|
||||
```
|
||||
@@ -78,4 +78,4 @@ Or type `/ask what's our deployment status?` in your connected Discord channel.
|
||||
- [Review the REST API reference](/docs/guides/org-api-keys)
|
||||
- [Browse all guides](/docs/guides)
|
||||
|
||||
Explore the [GitHub repo](https://github.com/Molecule-AI/molecule-core) for self-hosting options, or visit [moleculesai.app](https://moleculesai.app) for the hosted platform.
|
||||
Explore the [Gitea repo](https://git.moleculesai.app/molecule-ai/molecule-core) for self-hosting options, or visit [moleculesai.app](https://moleculesai.app) for the hosted platform.
|
||||
|
||||
@@ -0,0 +1,340 @@
|
||||
---
|
||||
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.
|
||||
|
||||
### `Workspace <id> was deleted on the platform...` from `get_workspace_info`
|
||||
|
||||
Since [#2429](https://github.com/Molecule-AI/molecule-core/pull/2449),
|
||||
`GET /workspaces/:id` returns **410 Gone** (not 200 + `status:"removed"`)
|
||||
when the workspace has been deleted. The MCP wheel's `get_workspace_info`
|
||||
tool surfaces this as a tailored error message:
|
||||
|
||||
```
|
||||
Workspace <id> was deleted on the platform at <removed_at>.
|
||||
Regenerate workspace + token from the canvas → Tokens tab.
|
||||
```
|
||||
|
||||
This is the **startup-time** counterpart to the heartbeat-401 escalation
|
||||
above. If you see it within seconds of starting your runtime (rather
|
||||
than after ~60s of heartbeat failures), the workspace was already gone
|
||||
when you connected — regenerate as instructed.
|
||||
|
||||
Audit-trail tools that intentionally want to inspect a removed workspace's
|
||||
metadata (admin dashboards, "show me deleted workspaces" tooling) can
|
||||
opt back into the legacy 200 + body shape via
|
||||
`GET /workspaces/<id>?include_removed=true`.
|
||||
|
||||
### `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
|
||||
@@ -17,7 +17,7 @@ description: Run the full Molecule AI stack on your own infrastructure.
|
||||
The fastest way to get Molecule AI running locally:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/Molecule-AI/molecule-core.git
|
||||
git clone https://git.moleculesai.app/molecule-ai/molecule-core.git
|
||||
cd molecule-core
|
||||
./scripts/dev-start.sh
|
||||
# Canvas: http://localhost:3000
|
||||
|
||||
+1
-1
@@ -237,4 +237,4 @@ Once your agent is connected to MCP, it stops being a chatbot with a scrollable
|
||||
|
||||
---
|
||||
|
||||
*Have questions or want to share what you're building with MCP? Open a discussion on [GitHub Discussions](https://github.com/Molecule-AI/molecule-core/discussions) or file an issue with the `enhancement` label.*
|
||||
*Have questions or want to share what you're building with MCP? File an issue with the `enhancement` label on the [molecule-core issue tracker](https://git.moleculesai.app/molecule-ai/molecule-core/issues).*
|
||||
Reference in New Issue
Block a user