MCP Management Skill

Version: 4.0.0 | Architecture: 3-Tier Progressive Disclosure | Categorization: Semantic AI

Overview

This skill enables the mcp-manager agent to efficiently route and execute MCP (Model Context Protocol) tools. By isolating MCP tool definitions in a dedicated subagent context, we reduce main agent token usage by 80-95%.

When to Use This Skill

Quick Reference

Tool Categories (AI-Generated)

Categories are generated by /mcp-refresh using semantic AI analysis. Common categories include:

Note: Your actual categories depend on your MCP configuration. Run /mcp-refresh to generate.

Most Common Tools

Routing Decision Tree

Task received
│
├─ Contains '__' (exact tool name)?
│  └─ YES → DIRECT PASSTHROUGH: Execute immediately
│
├─ Starts with 'BATCH:'?
│  └─ YES → Parse JSON array, execute sequentially
│
├─ Starts with 'CHAIN:'?
│  └─ YES → Parse chain, execute with variable passing
│
├─ Matches workflow trigger?
│  └─ YES → Check prerequisites, execute if needed
│
├─ Explicit tool name mentioned?
│  └─ YES → Use that tool directly
│
├─ Read .opencode/mcp-tools.json cache
│  └─ Match task keywords against category keywords
│
├─ Multiple categories match?
│  └─ YES → Prefer category with more keyword matches
│
└─ No match?
   └─ Search tool descriptions or ask for clarification

Advanced Features

Direct Passthrough

When you know the exact tool name (contains __), skip routing entirely:

Task: "Use MetaMCP_chrome-devtools__take_screenshot"
→ Executes directly without category lookup

Batch Operations

Execute multiple tools in one request using BATCH: prefix:

BATCH: [
  {"tool": "take_screenshot", "params": {}},
  {"tool": "get_title", "params": {}}
]

• •Maximum 10 tools per batch
• •Returns array of results in execution order
• •Partial failures reported per-tool

Tool Chaining

Chain tools with output passing using CHAIN: prefix:

CHAIN: [
  {"tool": "get_element", "params": {"selector": "#btn"}, "output_as": "el"},
  {"tool": "click", "params": {"element": "$el"}}
]

• •Use $varname to reference previous outputs
• •Maximum 5 tools per chain
• •Chain aborts on first failure

Retry Mechanism

All tool executions automatically retry on failure:

• •Up to 3 attempts
• •Delays: 0s → 1s → 2s
• •Failure report if all attempts fail:
  json

  {"tool": "name", "attempts": 3, "errors": [...], "suggestion": "..."}
  

Workflows

Define prerequisite steps that automatically execute before certain tool operations.

What are Workflows?

Workflows enforce best practices by requiring prerequisite steps before tool execution. For example:

• •Always inspect database structure before running queries
• •Take a page snapshot before clicking elements
• •Review PR details before merging

Quick Start

# Add a workflow from template
/mcp-workflow add --template database

# List active workflows
/mcp-workflow list

# Disable temporarily
/mcp-workflow disable database-safe-query

Built-in Templates

Workflow Modes

Full documentation: workflows.md

Cache Usage

Location: .opencode/mcp-tools.json

If Cache Exists

1. •Read and parse JSON (v2.0.0 schema)
2. •Use categories for keyword-based routing
3. •Use tools map for O(1) tool lookup
4. •Check generated_at - if >24h old, suggest /mcp-refresh

If Cache Missing

1. •Inform user: "Run /mcp-refresh to create tool cache"
2. •Fall back to dynamic tool discovery (slower)

Full cache schema: tool-execution.md

Execution Flow

1. •Parse Intent → Extract keywords from task
2. •Match Category → Find best category match
3. •Select Tool → Choose specific tool within category
4. •Execute → Call tool with mapped parameters
5. •Summarize → Return concise result to main agent

Detailed patterns: tool-execution.md

Result Handling

Summarization Rules

Always Include

• •Success/failure status
• •Key identifiers (IDs, paths, URLs)
• •Count of items (for lists)
• •Actionable next steps
• •Error details (if failed)

Full patterns: result-handling.md

Error Recovery

Full recovery procedures: error-handling.md

Example Invocations

Browser: Take Screenshot

Task: "Take a screenshot of the current page"
Tool: MetaMCP_chrome-devtools__take_screenshot
Result: "Screenshot saved to ./screenshot.png"

GitHub: Get PR

Task: "Get details of PR #123 in owner/repo"
Tool: MetaMCP_github-zengaming__get_pull_request
Params: { owner: "owner", repo: "repo", pull_number: 123 }
Result: "PR #123: 'Fix bug' by @user, open, +50/-20, 3 files"

Docs: Query Library

Task: "How do I use useState in React?"
1. MetaMCP_context7__resolve-library-id → "/facebook/react"
2. MetaMCP_context7__query-docs → Usage examples
Result: "useState returns [state, setState]. Example: ..."

Reference Documentation

Best Practices

1. •Prefer Cached Routing - Always check cache first
2. •Batch Operations - Execute related operations in sequence
3. •Summarize Aggressively - Main agent needs actions, not data
4. •Fail Fast - Ask for clarification rather than guessing
5. •Include Context - Errors should be actionable