mcp-installer - SKILL.md Agent Skill

name: mcp-installer description: |- Find, install, and configure MCP servers. Use proactively for MCP discovery, OAuth setup, env vars, stdio vs SSE transport, or troubleshooting MCP connections.

Examples: - user: "Add the filesystem MCP server" → read server file, add to mcpServers in opencode.json, verify transport type - user: "How do I use MCP with GitHub?" → check catalog, install @modelcontextprotocol/server-github, configure OAuth token - user: "MCP not connecting" → check transport type (stdio/SSE), verify args/command, check env vars are passed - user: "What MCPs are available?" → run list_mcps.py, show catalog with auth types and install commands

MCP Installer

Find, install, and configure MCP servers for OpenCode.

1. Search for MCP Server

Check local catalog first (quick check for already-documented MCPs):

python3 ~/.config/opencode/skill/mcp-installer/scripts/list_mcps.py

If not found locally, search online:

websearch("MCP server for [capability]")
webfetch("https://github.com/modelcontextprotocol/servers")
Check npm: @modelcontextprotocol/server-*
Check the MCP spec repo: https://github.com/modelcontextprotocol

2. Read MCP Details

For relevant matches, read the full MCP file:

references/mcps/<name>.md

Contains installation config, setup, features, and links.

3. Configure

Add the MCP config to user's opencode.json.

4. Document New MCPs

If you discovered a new MCP server online, you MUST document it for future reference in references/mcps/<name>.md using the template below.

5. Setup (if needed)

OAuth: Run opencode mcp auth <server-name>
API keys: Set environment variables
Other: Follow MCP-specific setup steps

Batching: Use the question tool for 2+ related questions. Single questions → plain text.

Syntax: header ≤12 chars, label 1-5 words, add "(Recommended)" to default.

When to ask: Multiple MCPs match the need, or setup requires OAuth/API keys.

Local MCP

{
  "mcp": {
    "name": {
      "type": "local",
      "command": ["npx", "-y", "@package/name"]
    }
  }
}

Remote MCP

{
  "mcp": {
    "name": {
      "type": "remote",
      "url": "https://example.com/mcp"
    }
  }
}

MCP Tool Management

MCPs expose tools. Control via the permission section using the tool name (usually the MCP name):

Global/Agent Permission:

{
  "permission": {
    "my-mcp": "deny",          // Disable all tools for this MCP
    "my-mcp*": "deny"          // Wildcard support
  }
}

Pattern-based control:

{
  "permission": {
    "my-mcp": {
      "safe_tool": "allow",
      "risky_tool": "ask",
      "*": "deny"
    }
  }
}

Legacy Configuration

Agents may occasionally work on legacy projects using outdated configuration fields (e.g., tools:). You MUST correct these to the modern permission: system when encountered.

OAuth

Remote MCPs with OAuth auto-authenticate:

opencode mcp auth <server-name>

Check status: opencode mcp list

You need...	Read this file
All config options (local, remote, oauth, env vars)	`references/configuration.md`
Common MCP server examples	`references/examples.md`
Troubleshooting issues	`references/troubleshooting.md`

Note: The local catalog (list_mcps.py) is a cache of discovered MCPs, not a complete list. SHOULD always search online if you don't find a match locally.

When discovering new MCP servers, you MUST document them:

Location: references/mcps/<name>.md

Template:

---
name: mcp-name
url: https://github.com/org/repo
type: local|remote
auth: oauth|api-key|none
description: One-line description
tags: [tag1, tag2]
---
# Display Name

Brief description.

## Installation

\`\`\`jsonc
{
  "mcp": {
    "name": {
      "type": "remote",
      "url": "https://example.com/mcp"
    }
  }
}
\`\`\`

## Setup

Steps for auth, env vars, etc.

## Features

- Feature 1
- Feature 2

## Links

- [GitHub](url)

Then run: python3 scripts/list_mcps.py to verify.

Frontmatter Fields

Field	Required	Purpose
`name`	Yes	MCP identifier (key in config)
`url`	No	Source URL
`type`	Yes	`local` or `remote`
`auth`	Yes	`oauth`, `api-key`, or `none`
`description`	Yes	One-liner for catalog
`tags`	No	Array of category tags