feat: mcp-search tool for lazy loading mcp

[TheOutdoorProgrammer]

edit: This was originally a rebase only, but I've since added some changes. Im still keeping this branch up to do date but its no longer solely a rebase.

original description

rebased #8771 onto the head of dev.

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]

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

Potential Related PR Found:

PR #8771 - "feat: add mcp_lazy mode for on-demand MCP tool loading"
#8771

Why it's related: This is the original PR that the current PR #12520 is based on. According to the PR description, PR #12520 is a rebase of PR #8771 onto the head of dev. Both PRs address the same feature: implementing lazy loading for MCP tools with the mcp_search tool to discover and call tools on-demand instead of loading them automatically.

Since PR #12520 is explicitly stated to be a rebase of PR #8771, you should verify whether #8771 is still open or if it should be closed in favor of #12520.

[rmk40]

This feature is absolutely needed — lazy MCP loading is one of the most requested capabilities and critical for users with many MCP servers. Thanks for rebasing and keeping this alive.

A few issues I noticed reviewing the diff:

MCP result handling is duplicated, not shared

This is the core issue. The MCP tool wrapping logic in prompt.ts (~80 lines) handles permissions, plugin hooks, content type parsing (text/image/resource), attachment creation, truncation, and metadata — then gets conditionally skipped when mcp_lazy is true. The call() function in mcp-search.ts reimplements a subset of this same logic, but incompletely. Extracting the MCP result processing into a shared function would fix the issues below and prevent them from diverging further as the codebase evolves.

MCP output fidelity loss in lazy call() path

A consequence of the duplication: the normal path preserves rich content — images become FilePart attachments, resource blobs are handled, and content is passed through for model output ordering. The lazy call() flattens everything to text ([Image: mime, N bytes]), dropping attachments entirely. MCP tools returning images or structured resources will produce degraded output when called through mcp_search.

Plugin hook payload inconsistency

Another consequence: the normal path passes args in the tool.execute.after trigger. The lazy call() path omits it. Plugins relying on args in after-hooks would break silently for lazy-loaded tools.

Search only matches server names

search filters on s.name.toLowerCase().includes(q) — searching for a tool name like "screenshot" returns nothing. Matching against tool names and descriptions would save round trips (list → scan → describe → call becomes search → call).

Generated file churn

The types.gen.ts and openapi.json changes are ~350 lines of reordering with no semantic changes. Regenerating cleanly against current dev would shrink the diff significantly.

Minor: the hasMcpSearch() check in prompt.ts is effectively dead code since mcp_lazy is already checked first and controls whether McpSearchTool is registered.

[TheOutdoorProgrammer]

Trying to keep the head of my fork synced so its easy to merge this. @thdxr @adamdotdevin @rekram1-node Is this something you guys would want to add? If its of use to you guys, Im happy to make sure its still updated properly. I just dont want to maintain updating it if its not. 😊

[manorit2001]

@rekram1-node / @thdxr would be really nice to have this, would be nice to save some on context as well as the cost when adding many MCPs..

[sangemaru]

This is an absolutely critical feature, really looking forward to this being merged into main soon

[ugurcancaykara]

+1

[advi2715]

Any updates on this? We really need a feature like this.

[TheOutdoorProgrammer]

@rmk40 implemented your suggestions 👍

[dbpolito]

i was about to write a plugin for this, then i found this PR... would love to see this on core...

[manorit2001]

@TheOutdoorProgrammer i can see some tests failing btw, any idea on them?

@thdxr @adamdotdevin @rekram1-node is there anything that you are looking for in the support, i don't think it's right to keep people hanging either if there are no intentions to merge this PR at all.

( If it's due to sheer traffic or PRs on this repo that's understadable but it is becoming a bit hard to track what you guys are looking for and what you are not, would be good to have some visbility on them )

[TheOutdoorProgrammer]

@manorit2001 Im not sure. Im happy to dive into the problems but I'd like to wait until I hear from the maintaining team if they want this feature or not (no is perfectly acceptable). Its becoming a bit of a chore maintaining this so it can merge cleanly.

If the maintainers can just give me a thumbs up or a thumbs down I will continue to maintain this PR or not based on their feedback.

[manorit2001]

ping @nexxeln ?

Also @TheOutdoorProgrammer , can you maybe look into possibility of having a plugin for this instead if possible, would be very handy to integrate if it it's not going in the main repo

[TheOutdoorProgrammer]

@manorit2001 I've actually seen a few plugins in some of the related issues.

• [FEATURE]: Claude-style Tool Search Tool Implementation in OpenCode #9461
• [Feature Request] MCP Tool Search - Lazy Loading for 85% Token Reduction #9350
• [FEATURE]: Lazy/dynamic loading for mcp tools #8277
• [FEATURE]: Filter which tools are loaded from MCP servers (includeTools/excludeTools) #7399

[nexxeln]

discussing internally

[itshahmir]

+1

[itshahmir]

+1