[Feature] Lazy-load MCP tool definitions to reduce token overhead

[jijoyo]

Problem

When multiple MCP servers are connected, ALL tool definitions from ALL servers are injected into the system prompt of EVERY conversation.

With 9 MCP servers connected (project-tools, supabase, agent-browser, chrome-devtools, playwright, memory, context7, sequential-thinking, fetch), this results in ~40,000-70,000 tokens of tool definitions loaded upfront — even if the user only needs 2-3 tools.

Users paying per-token to LLM providers (Anthropic, OpenAI, etc.) bear this cost on every single message.

Current behavior

• 9 MCP servers = ~250+ tool definitions
• Each tool definition = 50-200 tokens
• Total overhead: ~40-70k tokens per conversation
• User pays for ALL tools in EVERY message, even unused ones

Proposed solutions

1. Lazy tool loading — Only inject tool definitions when context suggests they are needed (e.g., if user mentions "deploy", load Supabase tools)
2. Tool profiles — Let users configure preset profiles (e.g., "dev", "deploy", "debug") with only relevant MCP servers
3. Tiered loading — Load essential tools (project-tools, bash, read, write) by default, load others on-demand via a /tools command

Impact

• Reduces token cost by 30-50k tokens per conversation
• No behavior change for users who want all tools available
• Better UX for cost-conscious users

Environment

• OpenCode version: latest
• OS: Windows
• MCP servers: 9 connected

[github-actions]

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

• [FEATURE]: Implement Dynamic/Lazy Loading for MCP Tool Schemas to Prevent Context Bloat #17482: [FEATURE]: Implement Dynamic/Lazy Loading for MCP Tool Schemas to Prevent Context Bloat (closed) — identical request for lazy/just-in-time MCP tool schema loading
• [Feature Request] MCP Tool Search - Lazy Loading for 85% Token Reduction #9350: [Feature Request] MCP Tool Search - Lazy Loading for 85% Token Reduction (closed) — same core idea of on-demand loading
• Feature Request: Two-Step MCP Tool Discovery for On-Demand Loading #16206: Feature Request: Two-Step MCP Tool Discovery for On-Demand Loading (closed) — same two-step discovery approach
• [FEATURE]: Lazy/dynamic loading for mcp tools #8277: [FEATURE]: Lazy/dynamic loading for mcp tools (closed) — direct duplicate
• [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 (closed) — same problem space
• [FEATURE] Reduce initial system prompt token overhead (~68k tokens before first user message) #26661: [FEATURE] Reduce initial system prompt token overhead (~68k tokens before first user message) (closed) — overlapping token overhead concern
• Feature request: MCP tool search / deferred schema loading (ENABLE_TOOL_SEARCH equivalent) #34873: Feature request: MCP tool search / deferred schema loading (closed) — deferred schema loading, same concept
• Tool descriptions consume excessive tokens in system prompt #11995: Tool descriptions consume excessive tokens in system prompt (open) — related open issue on token overhead from tool definitions

[blak0p]

Runtime-level lazy MCP resolution — transparent, zero round-trip

All current proposals (mcp_search, mcp_load_tools) put the burden on the agent: the agent has to (1) remember to search, (2) call a meta-tool, (3) wait until the next turn to actually use the tool. That is 2 turns to do 1 thing.

The metadata is already there

During the MCP initialize handshake, servers send serverInfo.name, serverInfo.version, and several SDKs (mcp-go, mcp-js) already include description or instructions fields. Opencode receives this but discards it — instead injecting full tool schemas for every server.

Proposal — 3 layers

1. Minimal manifest in system prompt (~50 tokens)

Instead of ~70k tokens of full schemas, inject only:

▶ playwright — Browser automation: navigate, click, snapshot
▶ supabase  — PostgreSQL DB: query, insert, schema management
▶ github    — Repo management: issues, PRs, code search
▶ figma     — Design components, export assets
▶ filesystem— File ops: read, write, search, glob

That is enough for the agent to decide which server it needs.

2. Runtime lazy resolution (the core)

The agent calls the tool directly:

playwright__browser_navigate({ url: "https://..." })

Opcodes intercepts, parses server=playwright, tool=browser_navigate, resolves the schema against the MCP server (or uses a cached tools/list), and injects it into the provider request in the same turn. No mcp_search, no extra round-trip, no lazy-loading awareness from the agent.

3. Provider-level defer (future)

When the provider supports it (Anthropic defer_loading: true, OpenAI tool_search), opencode sends all tools deferred and the provider expands the matching tool within the same request — zero server round-trips at all.

Comparison

Aspect	mcp_search (#12520)	Runtime resolution (this proposal)
Agent calls	2 calls (search + tool)	1 call (tool directly)
Turns to complete	2	1
Extra tokens	mcp_search invocation	0
Transparent to agent?	No	Yes
Uses server metadata?	No	Yes

Related issues

#8277, #8625, #9350, #9461, #12520, #7406

Thoughts?