fix(core): reduce intrusive MCP errors and deduplicate diagnostics (#20232)

docs/tools/mcp-server.md

@@ -1066,6 +1066,11 @@ command has no flags.
 gemini mcp list
 ```
 
+> **Note on Trust:** For security, `stdio` MCP servers (those using the
+> `command` property) are only tested and displayed as "Connected" if the
+> current folder is trusted. If the folder is untrusted, they will show as
+> "Disconnected". Use `gemini trust` to trust the current folder.
+
 **Example output:**
 
 ```sh
@@ -1074,6 +1079,23 @@ gemini mcp list
 ✗ sse-server: https://api.example.com/sse (sse) - Disconnected
 ```
 
+## Troubleshooting and Diagnostics
+
+To minimize noise during startup, MCP connection errors for background servers
+are "silent by default." If issues are detected during startup, a single
+informational hint will be shown: _"MCP issues detected. Run /mcp list for
+status."_
+
+Detailed, actionable diagnostics for a specific server are automatically
+re-enabled when:
+
+1.  You run an interactive command like `/mcp list`, `/mcp auth`, etc.
+2.  The model attempts to execute a tool from that server.
+3.  You invoke an MCP prompt from that server.
+
+You can also use `gemini mcp list` from your shell to see connection errors for
+all configured servers.
+
 ### Removing a server (`gemini mcp remove`)
 
 To delete a server from your configuration, use the `remove` command with the