code mode: catalog-listed MCP tools fail with Unknown tool unless invoked via execute #41389

Summary

In the Code Mode runtime, tools provided by an MCP server (e.g. chrome-devtools) are listed in the tool catalog but fail with Unknown tool when invoked directly. They only work when called through the execute runtime's tools object (tools["chrome-devtools"]["tool-name"]). The catalog documentation is ambiguous about this, which led to a time-consuming misdiagnosis (the MCP server was healthy all along).

Environment

• opencode version: 0.0.0-next-17055 (next channel)
• OS: Windows_NT 10.0.26200 (win32 x64)
• Terminal: Unavailable: terminal environment variables are not set
• Shell: C:\WINDOWS\system32\cmd.exe
• Install/channel: next
• Active plugins: None found in config

Reproduction

1. Configure an MCP server in ~/.config/opencode/opencode.jsonc, e.g.:

   "mcp": {
     "chrome-devtools": {
       "type": "local",
       "command": ["npx", "-y", "chrome-devtools-mcp@latest"]
     }
   }

2. Start opencode in Code Mode. The system prompt catalog lists the MCP tools, e.g. tools["chrome-devtools"].click(...).
3. Invoke one of the listed tools directly:

   <invoke name="chrome-devtools.list_pages">

4. Observe the error.

Expected Behavior

Either the catalog should indicate that tools are invoked via execute, or the listed tools should be directly invocable. Direct invocation should either work or be explicitly documented as unsupported.

Actual Behavior

Every direct invocation fails with:
{"error":{"type":"tool.execution","message":"Unknown tool: chrome-devtools.list_pages"}}

The same tools work when called inside execute:

await tools["chrome-devtools"]["list_pages"]({});

The opencode log confirms the MCP server was connected (message="mcp connected" server=chrome-devtools tools=29), so this is an invocation-runtime issue, not an MCP connection failure.

Additional Context

The catalog documentation is ambiguous. It states "The Code Mode catalog and search results are the complete set of tools available within Code Mode" (implying catalog tools are usable), and lists signatures like tools["chrome-devtools"].click(input: {...}) with no note that these must go through execute. Meanwhile, search itself also returned Unknown tool: search, so the catalog tools were unreachable through any documented path other than execute.

Misdiagnosis path taken before finding the fix: verified MCP config, launched the MCP server standalone (started fine), checked opencode2 service status, and parsed opencode.log — none of which were the problem. The resolution only came from re-reading the execute tool description: "Call tools through tools using only exact paths and signatures from the catalog."

Suggestion: document clearly in the Code Mode catalog that all tools (including MCP-provided) are invoked exclusively through the execute runtime, or accept direct invocation for catalog-listed tools.