[FEATURE]: Implement Dynamic/Lazy Loading for MCP Tool Schemas to Prevent Context Bloat

[wenbochang888]

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

Type

Performance Optimization / Token Efficiency

Description

Currently, OpenCode injects the entire input_schema of all connected MCP tools into the LLM context at the start of every session. While this follows a literal implementation of the MCP protocol, it creates a massive "Token Tax," especially when dealing with complex MCP servers.

I performed a comparative test between OpenCode and Cursor using an MCP server with a large input_schema:

Behavior	OpenCode	Cursor
Initial Context	Full schema loaded immediately	Minimal metadata (name/description) only
On Tool Call	N/A	Fetches input_schema just-in-time

The Problem

As discussed in previous issues like #2841, the current implementation causes the system prompt to grow linearly with the number and complexity of MCP tools. For power users with many MCP servers, this makes the tool almost unusable due to:

• High Token Costs: Paying for the same large schema in every single turn
• Context Exhaustion: Large schemas leave less room for actual code and reasoning
• Model Confusion: Overloading the prompt with irrelevant schemas can lead to hallucinations

Past Evidence of Context Bloat (Screenshots Attached)

I have attached a comparison showing the extreme token consumption caused by connecting a single MCP server (lark-mcp-docx):

Configuration	Token Count	Overhead
Without MCP	~21k tokens	-
With MCP Enabled	~168k tokens	+147k tokens

This demonstrates that the entire schema is being injected into the system prompt, consuming 86% of the context window before a single user message is even processed. This makes the tool unusable for large-scale MCP integrations.

Steps to Reproduce

1. Connect an MCP server with a very large/complex input_schema
2. Start a session and ask a simple question like "How is the weather?"
3. Inspect the tokens/context. OpenCode will show high token usage because it loaded the entire tool definition, whereas Cursor remains lean

Proposed Solution

Adopt a "Lazy Loading" or "Two-Step Discovery" mechanism similar to Cursor or the latest Claude Code updates:

1. Initial Context: Send only the name and a short description of the MCP tools
2. Just-in-Time Injection: When the LLM's intent matches a tool's description, the client should then inject the detailed input_schema for that specific tool before the final inference step
3. Toggle: Provide a setting to "Lazy Load" specific MCP servers

Additional Context

Addressing this would bring OpenCode's MCP efficiency on par with Cursor and Windsurf, making it much more viable for large-scale enterprise MCP integrations.

References

• Related issues: [FEATURE]:Add mcp search tool, reduce mcp tool occupying a lot of context #8625, high input token usage on a small project #1172, Context length issue / better context inspector #2841

[github-actions]

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
• [Feature Request] MCP Tool Search - Lazy Loading for 85% Token Reduction #9350: [Feature Request] MCP Tool Search - Lazy Loading for 85% Token Reduction
• Feature Request: Two-Step MCP Tool Discovery for On-Demand Loading #16206: Feature Request: Two-Step MCP Tool Discovery for On-Demand Loading
• [FEATURE]:Add mcp search tool, reduce mcp tool occupying a lot of context #8625: [FEATURE]: Add mcp search tool, reduce mcp tool occupying a lot of context

These issues cover very similar ground (lazy/on-demand loading of MCP tool schemas to reduce token usage). Please review them and consider adding your findings as comments there instead, or clarify how this request differs.

[wenbochang888]

To add to the above, the MCP repository is located here: https://github.com/larksuite/lark-openapi-mcp. Regardless of whether I use the cursor, Claude Code, or any other MCP tool, the overall context is significantly smaller than OpenCode's. The reason for this is currently unclear. However, OpenCode consumes 160,484 tokens even without using MCP, which is alarming. There is definitely a bug here, and I urge the developers to pay attention to this issue.

[TitoFigueroa]

Adding a bit more.

noticed that every time a subagent gets called, the base context is pretty huge. i'm running SDD workflows and each agent round is eating 10-12k tokens just for baseline context. with like 10 rounds per feature that's 120k minimum, and if you don't have prompt caching (which not everyone does) the costs stack up fast. doing 2-3 features a day for a month and you're looking at millions of tokens on pay-as-you-go which is basically wallet death. not sure what the solution is but wanted to flag this before more people get surprised by their bill.

[Docat0209]

Great discussion. I've been dealing with the same token bloat problem with large OpenAPI specs (some are 500KB+).

What I've found effective is a multi-level truncation approach:

1. Smart array slicing (show first 20 items, note "...and X more")
2. Depth limiting (max 5 levels deep)
3. Keep required fields, trim optional ones

This brought a 147K token spec down to ~8K without losing the info the model actually needs for tool calling.

Implementation is in mcp-openapi — the smart truncation logic specifically. Might be useful as a reference for designing the lazy loading layer.