[FEATURE]:Add mcp search tool, reduce mcp tool occupying a lot of context

Feature hasn't been suggested before.

I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

When MCP tool descriptions exceed 10% of the context window, they are automatically deferred and discovered via the MCPSearch tool instead of being loaded upfront. This reduces context usage for users with many MCP tools configured.

I found this great tool in Claude code, which I feel can make open code even more powerful

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

[FEATURE]: Lazy/dynamic loading for mcp tools #8277: [FEATURE]: Lazy/dynamic loading for mcp tools - Proposes lazy loading pattern to reduce context bloat from MCP tool schemas
[FEATURE]: Support MCP-CLI for on-demand loading of MCP tools for reduced token consumption #7406: [FEATURE]: Support MCP-CLI for on-demand loading of MCP tools for reduced token consumption - Suggests using MCP-CLI for on-demand tool loading
Feature Request: Tool to list and manage MCP servers to reduce context window #2418: Feature Request: Tool to list and manage MCP servers to reduce context window - Requests better context window management for MCP servers

Feel free to ignore if none of these address your specific case.

For references:

high level description: https://x.com/i/status/2011523109871108570
tool search specification: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool
original Claude Code issue: Feature Request: Lazy Loading for MCP Servers and Tools (95% context reduction possible) anthropics/claude-code#7336

I did a similar work in here: https://github.com/assagman/opencode-toolbox

I suspect this is similar to what claude code did last week, lazy loading the MCPs to reduce the context bloat. I would really love to see that in opencode as well.
My primary usecase is that I spawn multiple parallel subagents that do not need to use all tool all the time but they still consume all tokens for loading the mcp tools on every run.

This will be absolutely f amazing addition.

@thdxr

I've rebased #8771 here. I've been running it for a few days its working amazing. Would love this as a real feature of opencode @thdxr @rekram1-node

I also vote that we push the other feature requests to close in favor of this one, this one has the most thumbs up so it will get the most attention. I will comment on the others and ask they close theirs and then link back to this one. That way we just have one spot with this feature request.

Any news?

feat: lazy MCP loading with session-scoped activation

@TheOutdoorProgrammer

For anyone waiting on this: @TheOutdoorProgrammer's PR #12520 had accumulated merge conflicts with current dev. I've rebased it onto current upstream/dev, resolved all conflicts, and fixed a few bugs found during testing (broken tool parameter schema, LLM parameter name hallucination). See my comment on PR #12520 for details.

If you want to use it today, you can build from my fork:

git clone https://github.com/stephanschielke/opencode
cd opencode
git checkout fix/mcp-lazy-rebased-for-upstream
cd packages/opencode && bun install && bun run build

Then add to your opencode.json:

{
  "experimental": {
    "mcp_lazy": true
  }
}

This replaces all MCP tool schemas in context with a single mcp_search tool (~620 tokens). Agents call mcp_search(operation: "list"|"search"|"describe"|"call", ...) to discover and invoke MCP tools on demand. Tested with 9 connected MCP servers — saves ~21k tokens per prompt (for me)!

Also wanted to echo @laradji's point from the PR — local models finally work much better given the smaller initial context required. This is a real quality-of-life improvement for anyone running local/smaller models.

Thanks to @TheOutdoorProgrammer for the original implementation — really glad we found exactly what we were looking for instead of having to start from scratch!

One extra implementation detail that may be worth keeping explicit if this lands: the lazy-loading path should probably emit a small debug/telemetry receipt, not just save tokens.

The useful receipt shape I’d want while debugging a large MCP setup is roughly:

startup: which MCP server/tool indexes were loaded up front, plus token/count buckets
search: query hash/category, candidate tool ids, selected tool id, no raw query text required
expansion: which full tool definition was expanded into context and why
call: invoked server/tool id, argument/result redaction status, latency/status
budget: before/after context-token buckets, so the saving is measurable per session/subagent

Reason: once tools are discovered on demand, failures become harder to explain: did the agent not find the tool, did it not load the definition, or did it load it but call it wrong? A privacy-safe receipt gives users maintainers can inspect without dumping tool args/results or private prompts.

I made a tiny executable fixture for this pattern here, in case it helps as a concrete reference rather than just prose: https://github.com/caioribeiroclw-pixel/pluribus/blob/main/examples/context-input-evidence/mcp-tool-search-otel-trace.json

Not suggesting opencode adopt that schema as-is — the main point is to keep “what was indexed/searched/expanded/called” observable as part of the feature.

Research: Tool Count Impact on Reasoning Quality

I ran a multi-source investigation into the tool count problem. Key findings that may help inform the design direction:

Hard Numbers

Research from BFCL benchmarks and production case studies shows:

Tool Count	Accuracy	Source
≤20	96%+	BFCL v3 multi-step
40	~88%	Production case study (Presenc.ai)
80+	76%	BFCL v3, ~20% drop
120+	30%	Production case study, specialized domain

Both Anthropic and OpenAI officially recommend <20 tools per request. The accuracy drop is caused by attention dilution — not "can't find the tool". Even when the correct tool appears in the first 1024 tokens of the tool list, accuracy still drops 6.2% with 80+ tools present.

Caching Does Not Solve This

Prompt caching (Anthropic 90% cost reduction, OpenAI similar) solves the cost problem but not the reasoning quality problem. Cached KV tensors are reused, not freed — the model still attends to all tool definitions. This is the key insight: the problem is not token cost, it is model accuracy.

Existing Solutions in the Wild

Approach	Used By	Mechanism
Tool Search (single meta-tool)	Anthropic official docs	One `tool_search` replaces all tools
File-based discovery	Cursor	Tool descriptions in files, agent uses rg/jq
RAG retrieval	LangChain	Embed tool descriptions, retrieve top-K
Two-stage filtering	Academic (Tool Attention)	ISO scoring + prune, 47K→2.4K tokens

Broader Design: LRU + Always-Include + Discovery

The mcp_lazy / mcp_search approach in PR #12520 addresses MCP tools specifically. But the tool count problem extends beyond MCP — builtin tools, LSP tools, and skill descriptions all contribute to context bloat.

A complementary approach for all tools (not just MCP):

Always-include set: Core tools that every agent needs every turn (read, edit, write, shell, glob, grep, task, todo, skill, fetch) — ~12 tools, ~5K tokens
LRU-based pruning: Track tool usage per session. Inject only the top-N recently used tools on top of the always-include set. Target: ~25 total tools per request.
Discovery meta-tool: Similar to mcp_search, but for ALL hidden tools (including LSP, experimental, and rarely-used builtins).
Bootstrapping period: First 2-3 turns include all tools (no LRU), giving the model time to establish a working set before pruning kicks in.

Key Risks to Address

Silent task failure: Model won't call a discovery tool if it doesn't know a specific tool is missing. Mitigation: tool category hints in system prompt + generous bootstrapping period.
Discovery loops: Rate-limit discovery calls. After 2 calls in 5 turns, auto-include all tools.
Subagent inheritance: Subagents spawned via task need their own tool profiles, not just the parent's LRU set.
Tool-result replay: Prior turns may reference tools that are now hidden. Need ghost entries for provider compatibility.

Integration Point

The cleanest insertion point in current codebase is src/session/tools.ts resolve() — after collecting registry + MCP tools, before returning the final tool set. Usage tracking hooks into src/session/processor.ts where tool-call events are processed (line 377+, value.name provides the tool name).

I have a detailed design doc with Effect service patterns, pseudocode, and risk analysis if anyone is interested. Happy to collaborate on implementation.

we are going to try a codemode approach instead, we see that as being more useful than the tool search stuff

CodeMode has now landed through the split implementation PRs tracked in #34787. Final closeout: #34787 (comment). Keeping this issue closed.

Navigation Menu

Repository navigation

[FEATURE]:Add mcp search tool, reduce mcp tool occupying a lot of context #8625

Feature hasn't been suggested before.

Describe the enhancement you want to request

Research: Tool Count Impact on Reasoning Quality

Hard Numbers

Caching Does Not Solve This

Existing Solutions in the Wild

Broader Design: LRU + Always-Include + Discovery

Key Risks to Address

Integration Point

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[FEATURE]:Add mcp search tool, reduce mcp tool occupying a lot of context #8625

Description

Feature hasn't been suggested before.

Describe the enhancement you want to request

Activity

github-actions commented on Jan 15, 2026

saidelike commented on Jan 15, 2026

assagman commented on Jan 20, 2026

atanasna commented on Jan 25, 2026

TheOutdoorProgrammer commented on Feb 6, 2026

kvn1351 commented on Mar 25, 2026

stephanschielke commented on May 8, 2026

caioribeiroclw-pixel commented on May 22, 2026

Biemmmmm commented on May 30, 2026

Research: Tool Count Impact on Reasoning Quality

Hard Numbers

Caching Does Not Solve This

Existing Solutions in the Wild

Broader Design: LRU + Always-Include + Discovery

Key Risks to Address

Integration Point

rekram1-node commented on Jul 3, 2026

opencode-agent commented on Jul 4, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions