diff --git a/README.md b/README.md
index c701970bc..af0f54330 100644
--- a/README.md
+++ b/README.md
@@ -359,7 +359,7 @@ See full [Features Documentation](docs/reference/features.md).
 - **Hash-anchored Edit Tool**: `LINE#ID` references validate content before applying every change. Surgical edits, zero stale-line errors
 - **Context Injection**: Auto-inject AGENTS.md, README.md, conditional rules
 - **Claude Code Compatibility**: Full hook system, commands, skills, agents, MCPs
-- **Built-in MCPs**: websearch (Exa), context7 (docs), grep_app (GitHub search)
+- **Built-in MCPs**: websearch (Exa), context7 (docs), grep_app (GitHub search) — injected at runtime by the plugin; not visible in `opencode mcp list` (see [MCP docs](docs/reference/features.md#native-vs-plugin-injected-mcps))
 - **Session Tools**: List, read, search, and analyze session history
 - **Productivity Features**: Ralph Loop, Todo Enforcer, Comment Checker, Think Mode, and more
 - **Doctor Command**: Built-in diagnostics (`bunx oh-my-opencode doctor`) verify plugin registration, config, models, and environment
@@ -383,7 +383,7 @@ See [Configuration Documentation](docs/reference/configuration.md).
 - **Background Tasks**: Configure concurrency limits per provider/model
 - **Categories**: Domain-specific task delegation (`visual`, `business-logic`, custom)
 - **Hooks**: 54+ lifecycle hooks (61 with Team Mode), all configurable via `disabled_hooks`
-- **MCPs**: Built-in websearch (Exa), context7 (docs), grep_app (GitHub search)
+- **MCPs**: Built-in websearch (Exa), context7 (docs), grep_app (GitHub search) — runtime-injected, not shown in `opencode mcp list`
 - **LSP**: Full LSP support with refactoring tools
 - **Experimental**: Aggressive truncation, auto-resume, and more
 
diff --git a/docs/reference/features.md b/docs/reference/features.md
index c7891f38b..2bda8205f 100644
--- a/docs/reference/features.md
+++ b/docs/reference/features.md
@@ -913,6 +913,41 @@ The plugin uses a three-tier MCP architecture:
 2. Claude Code `.mcp.json` loader with `${VAR}` expansion
 3. Skill-embedded MCP servers declared in `SKILL.md` frontmatter
 
+### Native vs plugin-injected MCPs
+
+oh-my-openagent injects MCP servers at **runtime** through the OpenCode plugin API. This is fundamentally different from MCP servers you configure directly in `opencode.json`.
+
+Because `opencode mcp list` reads OpenCode's static configuration only, it **cannot see** MCPs that the plugin injects at runtime. This is expected behavior, not a bug:
+
+```
+# These are plugin-injected — they will NOT appear here
+$ opencode mcp list
+No MCP servers configured
+```
+
+To inspect which MCP servers oh-my-openagent is actually providing, run the doctor command:
+
+```bash
+bunx oh-my-openagent doctor --verbose
+```
+
+The three tiers of MCP servers and where they come from:
+
+| Tier | Source | Visible in `opencode mcp list`? |
+| ---- | ------ | ------------------------------- |
+| 1 — Built-in | Injected at runtime by oh-my-openagent (`websearch`, `context7`, `grep_app`) | No |
+| 2 — Claude Code `.mcp.json` | Loaded from `.mcp.json` files and merged in by oh-my-openagent at runtime | No |
+| 3 — Skill-embedded | Declared in `SKILL.md` frontmatter, spun up on demand per session | No |
+| — Native OpenCode | Configured directly in `opencode.json` under the `mcp` key, without the plugin | Yes |
+
+**Disabling built-in MCPs**: Use `disabled_mcps` in your plugin config:
+
+```jsonc
+{
+  "disabled_mcps": ["websearch", "grep_app"]
+}
+```
+
 ### Built-in MCPs
 
 | MCP           | Description                                                                                   |