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

[hohuuduc]

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.

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• codemode: Executor nested tool search fails in TUI #40611: Similar Unknown tool errors in Code Mode — Executor's nested tools.search() is routed against the outer Code Mode catalog instead of the runtime catalog, causing the same category of invocation failure for catalog-listed tools.

[opencode-agent]

This is the intended Code Mode behavior. When an MCP server participates in Code Mode, its tools are available inside the execute runtime rather than as directly invocable native tools.

The model-facing guidance makes that boundary explicit in several places:

• The catalog says it is the complete set of tools available within Code Mode.
• Catalog entries are rendered as JavaScript paths such as tools["chrome-devtools"]["list_pages"]({}), rather than native tool names.
• The execute tool is described as running JavaScript in the Code Mode runtime.
• Its description says: “Within { code }, the only callable tools are those explicitly listed in the Code Mode catalog instructions or returned by search.”
• It then says: “Call tools through tools using only exact paths and signatures from the catalog.”
• search is likewise a Code Mode runtime helper, not a directly invocable native tool.

We also checked chrome-devtools-mcp: it does not provide MCP initialization instructions that conflict with or override this guidance.

Closing as not reproducible because the reported Unknown tool response is expected for a direct invocation while Code Mode is enabled. If an agent independently emits a direct invocation despite this guidance, please open a new issue and attach the session transcript (including the model/provider and the prompt leading to the call) so we can investigate the actual model-facing sequence.