Skill MCP Manager
Relevant source files
The following files were used as context for generating this wiki page:
The Skill MCP Manager is a core architectural component of the Oh-My-OpenCode project designed to integrate Model Context Protocol (MCP) capabilities directly into specialized "skills." It serves as a bridge between AI agents and external tools, resources, and prompts provided by MCP servers that are specifically scoped to individual skills.
By embedding MCP configurations within skill definitions, the manager allows agents like Sisyphus and Atlas to dynamically discover and invoke server-side functionalities. This system supports a three-tier MCP architecture: built-in servers, project-specific .mcp.json configurations, and YAML-frontmatter embedded directly within Skill Markdown files.
Sources: src/tools/skill/tools.ts:74-88, AGENTS.md:158-161
Architecture and Integration
The Skill MCP Manager facilitates the discovery and execution of MCP capabilities through the skill tool. When a skill is loaded, the manager parses its configuration to identify associated MCP servers and their specific capabilities (Tools, Resources, and Prompts).
Discovery Flow
The discovery process occurs during skill loading. The manager inspects the skill's source—either a SKILL.md file with YAML frontmatter or a companion mcp.json file—to initialize the MCP client.
The manager ensures that MCP capabilities are contextually aware, meaning tools discovered via a specific skill are typically invoked using the skill_mcp tool with a reference to the specific server.
Sources: src/tools/skill/tools.ts:90-110, src/features/opencode-skill-loader/loader.test.ts:40-60
Data Structures and Interfaces
The system relies on several key interfaces to manage the lifecycle of an MCP connection within a skill session.
Core Interfaces
| Interface | Description |
|---|---|
SkillMcpManager | The primary interface for listing tools, resources, and prompts from a skill-associated MCP server. |
SkillMcpClientInfo | Metadata for identifying the MCP client, including serverName, skillName, and sessionID. |
SkillMcpServerContext | Contains the configuration and context required to establish a connection to an MCP server. |
Sources: src/tools/skill/tools.ts:15-18, src/tools/skill/tools.ts:80-88
MCP Configuration Format
MCP servers are defined within the mcp field of a skill's metadata. This can include environment variables with placeholder support.
name: example-skill
mcp:
sqlite:
command: uvx
args:
- mcp-server-sqlite
- --db-path
- ./data.db
env:
DB_KEY: "${DB_KEY}"
Sources: src/features/opencode-skill-loader/loader.test.ts:43-55, src/features/opencode-skill-loader/loader.test.ts:114-122
Capability Formatting and Presentation
The formatMcpCapabilities function is responsible for translating technical MCP schemas into a format readable by the agent. It retrieves the list of tools, resources, and prompts from the SkillMcpManager and generates a Markdown representation.
Capabilities Table
| Capability | Description | Verification Method |
|---|---|---|
| Tools | Executable functions with JSON input schemas. | Agent executes via skill_mcp. |
| Resources | Static or dynamic data URIs. | Accessed via URI listing. |
| Prompts | Pre-defined instruction templates. | Listed by name. |
If a connection fails, the manager catches the error and reports a concise failure message to the agent context instead of crashing the skill load.
Sources: src/tools/skill/tools.ts:90-143
Execution Protocol
Agents are instructed to use the skill_mcp tool specifically for invoking tools discovered through this manager. The configuration requires a sessionID to maintain continuity across multiple turns.
- Registration: The manager registers available tools into the agent's current capability set.
- Schema Injection: Detailed
inputSchemainformation is provided in the skill instructions so the agent understands how to structure arguments. - Invocation: The agent calls
skill_mcp(mcp_name="serverName", ...)to execute the remote function.
Sources: src/tools/skill/tools.ts:139-141, src/agents/sisyphus.ts:251-265
Conclusion
The Skill MCP Manager provides a modular and extensible way to enhance AI skills with external logic. By leveraging the Model Context Protocol, it ensures that specialized agents remain stateless yet highly capable, able to interact with diverse environments (like SQLite databases or Playwright browsers) through a unified configuration and discovery interface.