feat: add mcp_lazy mode for on-demand MCP tool loading

[xHeaven]

Closes #8625.

What does this PR do?

Adds a new experimental.mcp_lazy config option that prevents MCP tools from being loaded into context automatically. Instead, a new mcp_search tool is provided to discover and call MCP tools on-demand.

This reduces context usage for users with many MCP servers configured. When enabled:

• MCP tools are excluded from the tool list sent to the model
  • Instead, available MCP servers are injected into the system prompt in a compact format.
• The mcp_search tool allows listing, searching, describing, and calling MCP tools
• MCP servers show "Lazy" status in the /mcp dialog

The injected prompt:

<mcp_servers>
Available MCP servers: context7, firecrawl, playwright
Use mcp_search tool to discover and call tools from these servers.
</mcp_servers>

How did you verify your code works?

• Tested with experimental.mcp_lazy: true in config
• Verified MCP tools are not in context and mcp_search appears instead
• Tested all operations: list, search, describe, call
• Confirmed servers connect on-demand when calling tools

The tests were manual, there are no actual tests included here.

[github-actions]

Thanks for your contribution!

This PR doesn't have a linked issue. All PRs must reference an existing issue.

Please:

1. Open an issue describing the bug/feature (if one doesn't exist)
2. Add Fixes #<number> or Closes #<number> to this PR description

See CONTRIBUTING.md for details.

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

No duplicate PRs found

[DeveloperJose]

#8177 also proposes something similar

[xHeaven]

#8177 also proposes something similar

Damn, I completely missed that one. Our solutions differ a bit, I guess it comes down to preference. Also, honestly, I'm not sure I'd call either solution "complete", more like an idea of how this feature could be implemented.

[DeveloperJose]

There was also this one in November that was closed, #4717

Slightly different and with the idea of loading tools for certain turns and then unloading them

[spoons-and-mirrors]

yeah #4717 was a simpler implementation that just worked, maybe not the most feature full approach but did the trick fine. I closed it because it wasn't getting any attention and i wanted to help declutter opencode's growing PR number :D

[xHeaven]

yeah #4717 was a simpler implementation that just worked, maybe not the most feature full approach but did the trick fine. I closed it because it wasn't getting any attention and i wanted to help declutter opencode's growing PR number :D

That's probably what's going to happen to this PR, too. This is a great feature - probably not the best implementation -, but it's not getting the attention I would expect for something like this. I'm hoping the core contributors will pick up on it and make a better implementation.

[DeveloperJose]

There's another proposed implementation here https://github.com/famitzsy8/opencode-tool-search-tool

By @famitzsy8

If we are going to keep pushing this idea forward we might need to consolidate all the duplicate issues and PRs.

[atanasna]

Can you explain how this works with permissions, please?
If I have an subagent that only needs to use tools A,B,C from an MCP, but not tools D,E will the mcp_search only see A,B and C ?

[KennyDizi]

Looking forward to this PR being merged.

[strawberrymelonpanda]

Looking forward to this PR being merged.

If you're interested in it, as I am, probably best to just merge it locally. I don't know how OpenCode chooses which PRs to merge, but given the radio silence, I'd say odds aren't great.