opencode-embedded-skill-mcp

OpenCode Embedded Skill MCP Plugin

A standalone OpenCode plugin that enables skills to bundle and manage their own Model Context Protocol (MCP) servers.

This allows skills to bring their own tools, resources, and prompts without requiring manual server configuration in opencode.json.

Features

• Skill-Embedded MCPs: Configure MCP servers directly within skill definitions (markdown frontmatter or mcp.json).
• Zero Configuration: Skills manage their own MCP connections; just load the skill and use the tools.
• Connection Management:
  • Connection pooling per session/skill/server.
  • Lazy connection initialization (connects on first use).
  • Automatic idle cleanup (disconnects after 5 minutes of inactivity).
  • Session-scoped resource cleanup.
• Environment Variable Support: Full support for ${VAR} and ${VAR:-default} expansion in MCP configurations.

Installation

Add the plugin to your opencode.json:

{
  "plugin": ["opencode-embedded-skill-mcp"]
}

Or install it locally:

{
  "plugin": ["./path/to/opencode-embedded-skill-mcp"]
}

Usage

1. Create a Skill with Embedded MCP

You can define MCP servers in the skill's YAML frontmatter:

~/.config/opencode/skill/my-skill/SKILL.md

---
name: my-skill
description: "A skill that uses a custom MCP server"
mcp:
  my-server:
    command: ["npx", "-y", "@some/mcp-server"]
    environment:
      API_KEY: "${MY_API_KEY}"
---

# My Skill

This skill provides tools via the `my-server` MCP.

Alternatively, place an mcp.json file in the skill directory:

~/.config/opencode/skill/my-skill/mcp.json

{
  "mcpServers": {
    "my-server": {
      "command": ["npx", "-y", "@some/mcp-server"]
    }
  }
}

2. Load the Skill

In OpenCode:

skill(name="my-skill")

The plugin will load the skill and discover the capabilities of the embedded MCP server.

3. Use MCP Tools

Invoke tools, read resources, or get prompts using skill_mcp:

skill_mcp(mcp_name="my-server", tool_name="some-tool", arguments='{"key": "value"}')

Tools Provided

skill

Loads a skill and displays its instructions along with any available MCP capabilities (tools, resources, prompts).

• name: The name of the skill to load.

skill_mcp

Invokes an operation on a skill-embedded MCP server.

• mcp_name: The name of the MCP server (defined in the skill config).
• tool_name: (Optional) The name of the tool to call.
• resource_name: (Optional) The URI of the resource to read.
• prompt_name: (Optional) The name of the prompt to get.
• arguments: (Optional) JSON string of arguments for the operation.
• grep: (Optional) Regex pattern to filter the output.

Configuration Format

The MCP configuration supports the standard format:

interface McpServerConfig {
  command: string | string[];          // Command to execute (array recommended for args)
  environment?: Record<string, string> // Environment variables
}

License

MIT