opencode-mcp-triage

opencode-mcp-triage strips MCP tool definitions from the main prompt and routes them to dedicated subagents. Instead of loading every server's tools into every message, it uses keyword matching to activate only what you need. Cuts prompt token costs by eliminating MCP tool bloat — no LLM overhead, no extra API calls, zero setup.

What It Does

Normally all MCP servers load their tools into the system prompt and burn tokens on every message — even when irrelevant. Triage disables all MCP tools globally and routes work to scoped subagents that carry only the tools they need.

Without triage:   [supabase tools] [github tools] [render tools] ...  ← always burning tokens
With triage:      triage_mcp({ query }) → @github → github tools only

By default, each subagent carries one MCP server's tools. The main session carries zero. Token savings are static per MCP server — the same for every user with the same servers installed.

This plugin is OpenCode-only — it has no effect on Claude Desktop, Cursor, Windsurf, or any other tool using the same MCP config. Your MCP servers remain fully functional everywhere else.

Token Savings

Real data from this project's 6 MCP servers (measured with opencode-mcp-triage measure):

  TOKENS SAVED PER TURN (by routing MCPs to subagents)

  supabase      29 tools    19255 chars  ~ 4814 tokens
  netlify        9 tools    12322 chars  ~ 3081 tokens
  render        24 tools    28244 chars  ~ 7061 tokens
  clickup       51 tools   121319 chars  ~30330 tokens
  context7       2 tools     4605 chars  ~ 1151 tokens
  github        26 tools    15827 chars  ~ 3957 tokens
  ----------------------------------------------------
  TOTAL        141 tools   201572 chars  ~ 50394 tokens

  Each user turn saves ~50.394 tokens
  that would otherwise be sent with every prompt.

Tool definitions are static per MCP server — same savings for every user with the same servers installed. Run opencode-mcp-triage measure for live numbers based on your MCP inventory.

How It Works

The LLM calls triage_mcp() when it encounters a task that needs MCP tools. The plugin scores all subagents against the query using keyword matching and returns the best match.

User: "manage GitHub issues"
  │
  ▼
LLM: triage_mcp({ query: "manage GitHub issues" })
  │
  ▼
Plugin: scores subagents → returns best match
  @github         score=75  (matched: github ×3, issues in description ×1)
  @clickup        score=0
  gap=75 ≥ threshold(30) → HIGH CONFIDENCE
  │
  ▼
LLM: invokes @github subagent → carries only github tools

No LLM reasoning overhead. No extra API calls. Just fast deterministic matching.

Scoring Engine

• Subagent name matches: weight ×3
• MCP server name matches: weight ×3
• Description matches: weight ×1

Clear winner (gap ≥ 30): auto-routes. Too close: shows top 5 options. No matches: lists all available subagents.

Quick Start

npm install -g opencode-mcp-triage

Restart OpenCode. The plugin auto-disables all MCP tools and auto-creates one subagent per MCP server. No manual config needed. Type /mcp-triage status to verify.

Install

Global (recommended)

npm install -g opencode-mcp-triage

Restart OpenCode. /mcp-triage is available in every project.

Per-project

npm install opencode-mcp-triage

Restart OpenCode. /mcp-triage is available only in this project.

Dev / local

git clone https://github.com/cascharly/opencode-mcp-triage.git
cd opencode-mcp-triage
npm install

Add to your opencode config:

{ "plugin": ["file:/path/to/opencode-mcp-triage"] }

LLM Quick-Install

Copy-paste this into any LLM:

Install opencode-mcp-triage (https://github.com/cascharly/opencode-mcp-triage) — a deterministic MCP subagent router for OpenCode.

1. Run: npm install -g opencode-mcp-triage
2. If any errors occur, visit the repo link above and resolve them.
3. Tell me to restart OpenCode.

Configuration

The plugin handles everything automatically — no manual editing required. This section shows what gets generated and how to customize it if needed.

Auto-generated config

On first run, the plugin writes tool disable entries and auto-creates one subagent per MCP server:

{
  "tools": {
    "github_*": false,
    "render_*": false
  },
  "agent": {
    "github": {
      "description": "GitHub issue/PR management",
      "mode": "subagent",
      "tools": { "github_*": true }
    }
  }
}

Commands

Plugin Tools

| Tool | What it does | |---|---| | triage_mcp | Route a task to the right MCP subagent using keyword matching | | mcp_stats | Show routing status, subagent-to-server map, and coverage |

CLI Commands (available in terminal AND as /mcp-triage <command>)

| Command | What it does | |---|---| | status | Show MCP server status, hidden/exposed tools, subagent routing | | list | List all configured MCP servers and subagents | | measure | Connect to each MCP server and measure token savings per turn | | help | Show available commands |

Flags

| Flag | Where | What it does | |---|---|---| | --json | All commands | Machine-readable JSON output | | --verbose | measure | Show error diagnostics (HTTP codes, spawn errors, timeouts) | | --timeout=N | measure | Per-server timeout in seconds (default: 60) |

All CLI commands can be run directly in your terminal via npx opencode-mcp-triage <command> (e.g., npx opencode-mcp-triage measure --verbose). No OpenCode session needed.

Under the Hood

Plugin Activation

opencode-mcp-triage is a standard opencode plugin registered in the "plugin" array of opencode.jsonc (both ~/.config/opencode/opencode.jsonc globally and .opencode/opencode.jsonc per-project). On startup, opencode loads all listed plugins, making their tools and commands available. The plugin registers triage_mcp and mcp_stats in the system prompt alongside read, write, bash, etc.

How Tool Disabling Works

The plugin writes "servername_*": false entries to the "tools" block of your project config. OpenCode uses glob patterns to match tools — "github_*": false disables all tools from the github MCP server in the main session.

Main session tools:
  github_*: false          ← disabled, 0 tokens
  supabase_*: false        ← disabled, 0 tokens
  render_*: false          ← disabled, 0 tokens

@github subagent tools:
  github_*: true           ← enabled, ~4K tokens in subagent sessions only

MCP tool definitions are never loaded in the main session — they stay isolated in subagent contexts.

Auto-Created Subagents

On first run, the plugin creates one subagent per MCP server that doesn't already have one. The subagent name matches the server name, and its description comes from the server's description field.

Behavior:

• Already-covered MCP servers are skipped — existing user-defined subagents are never touched
• Deleting an auto-created subagent is respected — tracked via .opencode/mcp-triage.json
• Adding a new MCP server later auto-creates its subagent on reload (triage_mcp query: "reload")
• Power users can delete auto-created entries and define grouped subagents if desired, though separate subagents save more tokens per query

Config Caching

MCP server and subagent config reads are cached with a 5-second TTL. CLI toggles (add/remove MCP servers, change subagents) are picked up within 5 seconds without restarting OpenCode. Reload manually with triage_mcp query: "reload".

Uninstall

1. Remove "opencode-mcp-triage" from the "plugin" array in your config
2. Remove the auto-generated "servername_*": false entries from "tools"
3. (Optional) Remove any auto-created subagents from "agent"
4. (Optional) Delete the lock file at .opencode/mcp-triage.json
5. Delete the slash command:

# macOS / Linux
rm ~/.config/opencode/commands/mcp-triage.md

:: Windows (cmd)
del %USERPROFILE%\.config\opencode\commands\mcp-triage.md

Restart OpenCode. Clean.

Compatibility

• OpenCode 1.14+
• Node.js 18+ (for CLI)
• TypeScript 6+ (for development)

License

MIT

Author

Carlos Spagnoletti