opencode Integration

Overview

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

1. Declare Molecule as a remote MCP server

Create (or extend) opencode.json in your project root:

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

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 for rotation, revocation, and auditing.

3. Available tools

When opencode connects to the Molecule MCP endpoint the agent gains access to:

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:

{
  "tool": "delegate_task",
  "arguments": {
    "target": "research-lead",
    "task": "Summarise the last 7 days of commits in molecule-ai/molecule-core"
  }
}

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:

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:

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 — full tool catalogue for the @molecule-ai/mcp-server package
• Token Management — issue, rotate, and revoke workspace tokens
• External Agents — register any HTTP agent as a first-class workspace