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 <noreply@anthropic.com>
This commit is contained in:
parent
d566b84dcc
commit
fb4f86a42c
@ -20,6 +20,8 @@
|
||||
"troubleshooting",
|
||||
"---Runtimes---",
|
||||
"google-adk",
|
||||
"hermes"
|
||||
"hermes",
|
||||
"---Integrations---",
|
||||
"opencode"
|
||||
]
|
||||
}
|
||||
165
content/docs/opencode.mdx
Normal file
165
content/docs/opencode.mdx
Normal file
@ -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
|
||||
Loading…
Reference in New Issue
Block a user