---

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):

Copypython3 ~/.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:

Copyreferences/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

<question_tool>

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.

</question_tool>

Local MCP

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

Remote MCP

Copy{
  "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:

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

Pattern-based control:

Copy{
  "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:

Copyopencode mcp auth <server-name>

Check status: opencode mcp list

<reference_files>

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.

</reference_files>

<documenting_new_mcps>

When discovering new MCP servers, you MUST document them:

Location: references/mcps/<name>.md

Template:

Copy---
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

</documenting_new_mcps>