MCP Management Skill

Version: 2.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

Trigger	Category	Example
Browser automation	`browser`	"Take a screenshot", "Click the login button"
GitHub operations	`github`	"Get PR #123 details", "List open issues"
GraphQL queries	`graphql`	"Get the schema", "List available mutations"
Documentation lookup	`docs`	"How do I use useState?", "Find React docs"
Complex reasoning	`reasoning`	"Analyze this step by step"

Quick Reference

Tool Categories (AI-Generated)

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

Category	Description	Example Tools
browser-automation	Web interaction, screenshots, DOM	click, screenshot, navigate
version-control	Git, PRs, issues, code review	get_pull_request, list_issues
documentation	Library docs, API references	query-docs, resolve-library-id
communication	Messaging, notifications	post_message, list_channels
database	SQL queries, data operations	query, insert, update

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

Most Common Tools

Task	Tool	Category
Screenshot	`take_screenshot`	browser
Click element	`click`	browser
Fill form	`fill`, `fill_form`	browser
Navigate	`navigate_page`	browser
Get page content	`take_snapshot`	browser
Get PR details	`get_pull_request`	github
List issues	`list_issues`	github
Search code	`search_code`	github
Query docs	`query-docs`	docs
Step-by-step analysis	`sequentialthinking`	reasoning

Routing Decision Tree

code

Task received
│
├─ 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

Cache Usage

Location: .opencode/mcp-tools.json

If Cache Exists

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

If Cache Missing

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

Full cache schema: tool-execution.md

Execution Flow

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

Detailed patterns: tool-execution.md

Result Handling

Summarization Rules

Result Type	Action
Large (>1000 chars)	Extract key info only
File operations	"File X read/written successfully (N chars)"
Data queries	"Found N items. First 3: [...]"
Screenshots	"Screenshot saved to /path"
Errors	Include error + suggestions

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

Error	Recovery
Tool not found	Suggest similar tools
Execution failed	Include context + retry suggestions
Timeout	Report partial result + suggestions
Cache missing	Prompt `/mcp-refresh`

Full recovery procedures: error-handling.md

Example Invocations

Browser: Take Screenshot

code

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

GitHub: Get PR

code

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

code

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

Document	Content	When to Read
tool-categories.md	Full tool lists per category	Need specific tool
tool-execution.md	Routing algorithm, cache schema	Complex routing
result-handling.md	Summarization patterns	Large results
error-handling.md	Recovery procedures	Errors occur

Best Practices

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