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 in the documentation section.

5. Setup (if needed)

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

Question Tool Usage

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

Syntax: header max 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. You SHOULD always search online if you don't find a match locally.

Documenting New MCPs

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

mcp-installer

1. Search for MCP Server