molecule-ai/docs
35
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #102 from Molecule-AI/docs/runtime-mcp-notifications-and-pitfalls

Browse Source 
docs(runtime-mcp): document push-UX + expand troubleshooting
This commit is contained in:
Hongming Wang 2026-04-30 20:12:36 -07:00 committed by GitHub
commit 7df9bb6631
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 51 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
content/docs/runtime-mcp.mdx
View File

@ -168,6 +168,20 @@ External runtimes can't accept inbound HTTP, so the wheel polls
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.
## Heartbeat & lifecycle
The wheel spawns a daemon thread that POSTs `/registry/heartbeat` every
@ -222,6 +236,43 @@ 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 |