From fb4f86a42cf4736c852361af01cded3a025e3114 Mon Sep 17 00:00:00 2001 From: Molecule AI Documentation Specialist Date: Fri, 17 Apr 2026 23:36:10 +0000 Subject: [PATCH] docs(site): opencode MCP bridge integration page (#800) Pairs with monorepo PRs #840 (opencode MCP bridge) and #842 (org-template + integration guide). Adds opencode.mdx with prerequisites, opencode.json config, token issuance, available tools, transport options, and SAFE-T1401/T1201 security notes. Adds ---Integrations--- nav section to meta.json. Co-Authored-By: Claude Sonnet 4.6 --- content/docs/meta.json | 4 +- content/docs/opencode.mdx | 165 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 168 insertions(+), 1 deletion(-) create mode 100644 content/docs/opencode.mdx diff --git a/content/docs/meta.json b/content/docs/meta.json index b1a6882..140b7d2 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -20,6 +20,8 @@ "troubleshooting", "---Runtimes---", "google-adk", - "hermes" + "hermes", + "---Integrations---", + "opencode" ] } \ No newline at end of file diff --git a/content/docs/opencode.mdx b/content/docs/opencode.mdx new file mode 100644 index 0000000..4c4716c --- /dev/null +++ b/content/docs/opencode.mdx @@ -0,0 +1,165 @@ +--- +title: opencode Integration +description: Use opencode as an AI coding agent connected to your Molecule AI workspace via remote MCP. +--- + +## Overview + +[opencode](https://opencode.ai) is an AI coding agent that supports remote MCP +servers via `opencode.json`. With Molecule AI's MCP bridge you can wire opencode +directly to your workspace — giving it the full A2A tool surface +(`delegate_task`, `list_peers`, `recall_memory`, and more) over a standard +`Authorization: Bearer` connection. + +``` +opencode (terminal) + ↕ opencode.json declares remote MCP +Molecule AI MCP endpoint + ↕ WorkspaceAuth middleware +Your workspace agent +``` + +--- + +## Prerequisites + +- A running Molecule AI platform (`MOLECULE_MCP_URL` — e.g. `https://api.molecule.ai`) +- A workspace-scoped bearer token (`MOLECULE_MCP_TOKEN`) issued via the platform API (see [Token Management](/docs/tokens)) + +--- + +## 1. Declare Molecule as a remote MCP server + +Create (or extend) `opencode.json` in your project root: + +```json +{ + "mcpServers": { + "molecule": { + "type": "remote", + "url": "${MOLECULE_MCP_URL}/workspaces/${WORKSPACE_ID}/mcp", + "headers": { "Authorization": "Bearer ${MOLECULE_MCP_TOKEN}" }, + "description": "Molecule AI A2A orchestration — delegate_task, list_peers, check_task_status" + } + } +} +``` + +> ⚠️ **Never embed the token in the URL** (e.g. `?token=…`). Always use the +> `Authorization: Bearer` header — URL-embedded tokens appear in server logs, +> browser history, and Git history if the file is committed. + +A pre-configured template is available in +`org-templates/molecule-dev/opencode.json` in the monorepo. + +--- + +## 2. Obtain a workspace-scoped token + +```bash +curl -X POST https://$MOLECULE_MCP_URL/workspaces/$WORKSPACE_ID/tokens \ + -H "Authorization: Bearer $ADMIN_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"name": "opencode-agent", "scopes": ["mcp:read", "mcp:delegate"]}' +``` + +Store the returned token as `MOLECULE_MCP_TOKEN` in your `.env`. + +See [Token Management](/docs/tokens) for rotation, revocation, and auditing. + +--- + +## 3. Available tools + +When opencode connects to the Molecule MCP endpoint the agent gains access to: + +| Tool | Description | +|------|-------------| +| `list_peers` | Discover available workspaces in your org | +| `delegate_task` | Send a task to a peer workspace and wait for the result | +| `delegate_task_async` | Fire-and-forget task delegation; returns a `task_id` | +| `check_task_status` | Poll an async delegation by `task_id` | +| `commit_memory` | Persist information to `LOCAL` or `TEAM` memory scope | +| `recall_memory` | Search previously committed memories | + +### Restricted tools + +- **`send_message_to_user`** — disabled for remote MCP callers by default. Enable + with `MOLECULE_MCP_ALLOW_SEND_MESSAGE=true` in your platform env. +- **`GLOBAL` memory scope** — `commit_memory` with `scope: GLOBAL` is blocked for + external agents. `LOCAL` and `TEAM` scopes are always available. + +--- + +## 4. Example: delegate a research task + +Once connected, opencode can call Molecule tools directly in its tool loop: + +```json +{ + "tool": "delegate_task", + "arguments": { + "target": "research-lead", + "task": "Summarise the last 7 days of commits in Molecule-AI/molecule-monorepo" + } +} +``` + +The platform routes the task to your `research-lead` workspace and streams the +response back to opencode. + +--- + +## 5. Two transports + +The MCP endpoint supports two transports — opencode auto-selects: + +| Transport | Endpoint | Notes | +|-----------|----------|-------| +| Streamable HTTP (primary) | `POST /workspaces/:id/mcp` | MCP 2024-11-05, recommended | +| SSE (backwards compat) | `GET /workspaces/:id/mcp/stream` | Legacy clients | + +--- + +## 6. Security notes + +### Org topology exposure (SAFE-T1401) + +`list_peers` returns the full set of workspace names and roles visible to your +workspace. Any opencode agent with a valid `MOLECULE_MCP_TOKEN` can enumerate +your org topology. Issue tokens to only the workspaces that need peer visibility. + +### Tool surface audit (SAFE-T1201) + +The full `@molecule-ai/mcp-server` package exposes additional tools beyond those +listed above. A complete SAFE-T1201 audit is in progress. **Until that audit +completes, do not expose the MCP server to untrusted external agents in +production.** + +### Token scoping + +Issue tokens with the minimum required scopes (`mcp:read`, `mcp:delegate`). +Rotate tokens regularly. Revoke via `DELETE /workspaces/:id/tokens/:token_id`. + +--- + +## 7. Environment variables + +Add to your `.env`: + +```bash +MOLECULE_MCP_URL=https://api.molecule.ai # or http://localhost:8080 for local dev +MOLECULE_MCP_TOKEN= # workspace-scoped bearer token (step 2) +WORKSPACE_ID= # UUID of the workspace opencode acts as + # find it in the Canvas sidebar or GET /workspaces +``` + +See `.env.example` in the monorepo for the full canonical reference. + +--- + +## Related + +- [MCP Server](/docs/mcp-server) — full tool catalogue for the `@molecule-ai/mcp-server` package +- [Token Management](/docs/tokens) — issue, rotate, and revoke workspace tokens +- [External Agents](/docs/external-agents) — register any HTTP agent as a first-class workspace