diff --git a/packages/core/src/plugin/skill/opencode.md b/packages/core/src/plugin/skill/opencode.md
index eed550167a..3ffc699cc2 100644
--- a/packages/core/src/plugin/skill/opencode.md
+++ b/packages/core/src/plugin/skill/opencode.md
@@ -63,6 +63,33 @@ examples, but do not fetch it to determine the V2 configuration shape.
 See the [full configuration guide](https://opencode.ai/v2/docs/config) for
 every field, examples, config locations, and links to dedicated feature guides.
 
+## [MCP servers](https://opencode.ai/v2/docs/mcp-servers)
+
+Configure MCP servers under `mcp.servers`. Prefer the CLI because it preserves
+unrelated configuration. Use `--global` when the user asks to set up a service
+for themselves without limiting it to the current project; omit it when they
+explicitly want project-local configuration.
+
+```sh
+opencode2 mcp add <name> --global --url <remote-url>
+opencode2 mcp list
+```
+
+Remote servers use OAuth by default. If `mcp list` reports that a server needs
+authentication, run the OAuth flow and then verify the connection:
+
+```sh
+opencode2 mcp auth <name>
+opencode2 mcp list
+```
+
+The auth command prints an authorization URL, waits for the browser redirect,
+and stores credentials outside the OpenCode configuration. Do not ask for or
+store an API key when the server supports OAuth. Use header-based credentials
+only when OAuth is unavailable or the user explicitly requires them, and use an
+environment substitution such as `{env:MCP_API_KEY}` instead of writing a
+secret into configuration.
+
 ## [V1 to V2 migration](https://opencode.ai/v2/docs/migrate-v1)
 
 For any request to migrate OpenCode configuration, agents, commands, skills,