docs/content/docs/opencode.mdx

---
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