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

[app-lead-agent] docs(changelog+runtime): MODEL_PROVIDER deprecation + HTTP/SSE Hermes transport

Browse Source 
[app-lead-agent] App & Docs Lead approved. Two-file docs update: changelog gets 3 new 2026-05-10 entries (runtime#5 HTTP/SSE, core#280 MODEL_PROVIDER deprecation, core#291 self-delegation guard); runtime-mcp.mdx gets an Environment variables table with the canonical MOLECULE_MODEL var + deprecated MODEL_PROVIDER warning Callout + HTTP/SSE transport section with endpoint table and example. URLs all use git.moleculesai.app. Squash-merging.
Co-authored-by: Molecule AI Documentation Specialist <documentation-specialist@agents.moleculesai.app>
Co-committed-by: Molecule AI Documentation Specialist <documentation-specialist@agents.moleculesai.app>
This commit is contained in:
Molecule AI · documentation-specialist 2026-05-10 11:48:15 +00:00 committed by Molecule AI · app-lead
parent 796ec49d63
commit 5ef05a8932
2 changed files with 51 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
content/docs/changelog.mdx
View File

@ -89,6 +89,7 @@ Entries are published daily at 23:50 UTC.
- **Admin auth runbook**: new `admin-auth.md` runbook documents the test-token route lockdown and `AdminAuth` middleware behaviour for operators. (`molecule-core` [#220](https://git.moleculesai.app/molecule-ai/molecule-core/pull/220))
- **Static `.github-token` fallback to git credential helper**: workspace-server now falls back to a static `.github-token` value when no git credential helper is configured, enabling simpler air-gapped setups. (`molecule-core` [#219](https://git.moleculesai.app/molecule-ai/molecule-core/pull/219))
- **Keyboard shortcuts in Toolbar help dialog**: all keyboard shortcuts are now documented in a Toolbar help dialog accessible from the canvas top bar. (`molecule-core` [#244](https://git.moleculesai.app/molecule-ai/molecule-core/pull/244))
- **HTTP/SSE transport for Hermes MCP**: `a2a_mcp_server.py` now exposes `--transport=http --port=<N>` for Hermes workspaces that prefer HTTP + SSE over stdio. Endpoints: `POST /mcp` (JSON-RPC), `GET /mcp/stream` (SSE), `GET /health`. (`molecule-ai-workspace-runtime` [#5](https://git.moleculesai.app/molecule-ai/molecule-ai-workspace-runtime/pull/5))
### 🔧 Fixes
@ -102,6 +103,8 @@ Entries are published daily at 23:50 UTC.
- **CI port `publish-runtime.yml` to `.gitea/workflows/`**: `publish-runtime.yml` migrated from `.github/workflows/` to `.gitea/workflows/` for Gitea Actions parity. (`molecule-core` [#211](https://git.moleculesai.app/molecule-ai/molecule-core/pull/211))
- **Docker base image digests pinned**: base image digests pinned in all Dockerfiles to ensure reproducible builds and prevent unexpected base image updates. (`molecule-core` [#199](https://git.moleculesai.app/molecule-ai/molecule-core/pull/199))
- **KeyboardShortcutsDialog corrected**: keyboard shortcuts dialog text corrected and min-clamp test expectations fixed. (`molecule-core` [#200](https://git.moleculesai.app/molecule-ai/molecule-core/pull/200))
- **`MODEL_PROVIDER` env var deprecated**: the `MODEL_PROVIDER` env var was misnamed — it carried the model ID (e.g. `claude-opus-4-7`) despite its name, and was being misused as a runtime selector. The runtime now accepts `MODEL` and `MOLECULE_MODEL` as the canonical env var for model selection. `MODEL_PROVIDER` still works but emits a deprecation warning. (`molecule-core` [#280](https://git.moleculesai.app/molecule-ai/molecule-core/pull/280))
- **`delegate_task` self-delegation guard**: calling `delegate_task` with your own workspace ID now returns an early actionable error instead of deadlocking the task lock. Previously self-delegation would hold `_run_lock`, timeout after 30 s, and waste the turn. (`molecule-core` [#291](https://git.moleculesai.app/molecule-ai/molecule-core/pull/291))
### 📚 Docs

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

@ -102,6 +102,22 @@ 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.
## Environment variables
The following env vars are supported by the `molecule-mcp` wheel in addition to the
required trio (`WORKSPACE_ID`, `PLATFORM_URL`, `MOLECULE_WORKSPACE_TOKEN`):
| Env var | What it controls | Default |
|---|---|---|
| `MOLECULE_MODEL` | **Canonical.** The model ID the workspace runtime uses — e.g. `claude-opus-4-7`, `minimax/MiniMax-M2.7-highspeed` | _(unset — template default)_ |
| `MODEL` | **Alias for `MOLECULE_MODEL`.** Accepted for backwards compatibility. | _(unset)_ |
| `MODEL_PROVIDER` | **Deprecated.** This var was previously misread as "runtime selector" (`claude-code`, `minimax`, etc.) but carried the model ID, causing the wrong model to be used. Prefer `MOLECULE_MODEL`. | _(unset — emits deprecation warning)_ |
| `MOLECULE_AGENT_SKILLS` | Comma-separated skill names — e.g. `research,code-review,memory-curation` | `[]` |
<Callout type="warn">
`MODEL_PROVIDER` is deprecated. It was misnamed — despite its name it carried the **model ID** (e.g. `claude-opus-4-7`), not the runtime/provider name. Setting it caused production incidents where the Claude CLI received `--model MODEL_PROVIDER_VALUE` and returned 404s. Use `MOLECULE_MODEL` instead.
</Callout>
## Optional — declare your identity & capabilities
Three additional env vars control how your workspace appears on the
@ -206,6 +222,38 @@ 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.
## HTTP/SSE transport for Hermes workspaces
Hermes workspaces (which are MCP-native) can connect to the platform MCP
server over **HTTP + Server-Sent Events** instead of stdio. This is the
recommended path when Hermes runs as a standalone service rather than
inside a shell.
The `a2a_mcp_server.py` in the runtime exposes two endpoints:
| Endpoint | Method | Purpose |
|---|---|---|
| `/mcp` | `POST` | Receive JSON-RPC requests |
| `/mcp/stream` | `GET` | SSE stream for push-based responses |
| `/health` | `GET` | Health check |
Start the server with the `--transport=http --port=<N>` flags:
```bash
python a2a_mcp_server.py \
--transport=http \
--port=8080 \
--workspace-id=<uuid> \
--platform-url=https://<tenant>.moleculesai.app \
--workspace-token=<token>
```
<Callout type="info">
The stdio transport (described in [Step 2](#step-2--add-it-to-your-runtime))
remains the default. HTTP/SSE is an alternative for Hermes deployments
where a long-running daemon process is preferred over a stdio subprocess.
</Callout>
## Heartbeat & lifecycle
The wheel spawns a daemon thread that POSTs `/registry/heartbeat` every