[FEATURE]: Filter which tools are loaded from MCP servers (includeTools/excludeTools)

[marcusquinn]

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

Problem

MCP servers often expose many tools, but agents typically need only a subset. Currently, enabling an MCP loads all its tools into the context window, adding significant token overhead.

Example: The chrome-devtools MCP provides 26 tools (~17k tokens). A UI preview agent might only need 4 of them (~1.5k tokens).

Proposed Solution

Add includeTools and/or excludeTools to MCP configuration:

{
  "mcp": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"],
      "includeTools": ["navigate_page", "take_screenshot", "new_page", "list_pages"]
    }
  }
}

Or with glob patterns:

{
  "mcp": {
    "github": {
      "includeTools": ["create_*", "list_*"],
      "excludeTools": ["*_dangerous_*"]
    }
  }
}

Per-Agent Override

Combined with per-agent MCP enabling, this allows fine-grained control:

{
  "mcp": {
    "chrome-devtools": {
      "enabled": false,
      "includeTools": ["navigate_page", "take_screenshot", "new_page", "list_pages"]
    }
  },
  "agent": {
    "ui-preview": {
      "mcp": {
        "chrome-devtools": { "enabled": true }
      }
    }
  }
}

Prior Art

Amp recently shipped this feature: Lazy-load MCP with Skills

Their implementation uses a companion mcp.json file per skill. The approach proposed here integrates with OpenCode's existing centralized config pattern.

Benefits

• Token savings: Load only needed tools (17k → 1.5k in the chrome-devtools example)
• Reduced confusion: LLM sees only relevant tools
• Backward compatible: No includeTools = all tools (current behavior)

Related Issues

• Reduce token overhead: Task tool injects all subagent descriptions into system prompt #7269 - Subagent list filtering (complementary - filters subagents, not MCP tools)
• [FEATURE]: Provider/Model-specific MCP servers #6024 - Provider/model-specific MCPs (complementary - when to load MCPs)
• [FEATURE]: Tool call descriptions as skills #7362 - Tool descriptions as skills (similar goal, different approach)

Contribution

Happy to submit a PR for this if the approach is acceptable. We're tracking this in aidevops and can implement a workaround in the meantime, but native OpenCode support would be cleaner.

[github-actions]

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

• MCP tool blocking not working - agents can still see and access disabled tools #3756: MCP tool blocking not working - agents can still see and access disabled tools
• [feature request]: ability to dynamic turn on mcp server for specific agent #2953: [feature request]: ability to dynamic turn on mcp server for specific agent
• [FEATURE]: Allow per-project MCP enabled/disabled overrides #4525: [FEATURE]: Allow per-project MCP enabled/disabled overrides
• [FEATURE]: Allow to enable MCP on a per-agent basis #5373: [FEATURE]: Allow to enable MCP on a per-agent basis
• [FEATURE]: Provider/Model-specific MCP servers #6024: Provider/model-specific MCPs (related feature request you mentioned)
• Reduce token overhead: Task tool injects all subagent descriptions into system prompt #7269: Reduce token overhead: Task tool injects all subagent descriptions into system prompt (shares token optimization goal)

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

[marcusquinn]

Thanks for flagging these! After reviewing:

Issue	Status	What it addresses	How #7399 differs
#3756	Closed	Bug: disabled tools still visible	Bug fix, not feature
#2953	Open	Enable/disable MCP per agent	All-or-nothing - entire MCP on/off
#4525	Closed	Per-project MCP overrides	Project-level, still all-or-nothing
#5373	Closed	Per-agent MCP enable/disable	Same as #2953 - entire MCP
#6024	Open	Provider/model-specific MCPs	When to load MCPs, not which tools
#7269	Open (mine)	Subagent list filtering	Filters subagents, not MCP tools

The gap this issue fills:

All existing issues address enabling/disabling entire MCP servers. None address filtering which tools within an MCP are loaded.

Example: chrome-devtools MCP has 26 tools. With existing features, I can:

• Enable it globally (26 tools, ~17k tokens)
• Disable it globally (0 tools)
• Enable it per-agent (still 26 tools)

With includeTools, I could load only 4 specific tools (~1.5k tokens) - a 91% token reduction while keeping the functionality I need.

This is complementary to per-agent MCP enabling (#2953, #5373) - you'd use both together for maximum control.