diff --git a/src/main/mcpServers/hub/index.ts b/src/main/mcpServers/hub/index.ts
index 29a52bafe8..08b3372c26 100644
--- a/src/main/mcpServers/hub/index.ts
+++ b/src/main/mcpServers/hub/index.ts
@@ -9,6 +9,18 @@ import type { ExecInput, SearchQuery } from './types'
 
 const logger = loggerService.withContext('MCPServer:Hub')
 
+/**
+ * Hub MCP Server - A meta-server that aggregates all active MCP servers.
+ *
+ * This server is NOT included in builtinMCPServers because:
+ * 1. It aggregates tools from all other MCP servers, not a standalone tool provider
+ * 2. It's designed for LLM "code mode" - enabling AI to discover and call tools programmatically
+ * 3. It should be auto-enabled when code mode features are used, not manually installed by users
+ *
+ * The server exposes two tools:
+ * - `search`: Find available tools by keywords, returns JS function signatures
+ * - `exec`: Execute JavaScript code that calls discovered tools
+ */
 export class HubServer {
   public server: Server
   private toolRegistry: ToolRegistry
diff --git a/src/renderer/src/store/mcp.ts b/src/renderer/src/store/mcp.ts
index 3b94248401..72cb4e39dc 100644
--- a/src/renderer/src/store/mcp.ts
+++ b/src/renderer/src/store/mcp.ts
@@ -86,6 +86,14 @@ export { mcpSlice }
 // Export the reducer as default export
 export default mcpSlice.reducer
 
+/**
+ * User-installable built-in MCP servers shown in the UI.
+ *
+ * Note: The `hub` server (@cherry/hub) is intentionally excluded because:
+ * - It's a meta-server that aggregates all other MCP servers
+ * - It's designed for LLM code mode, not direct user interaction
+ * - It should be auto-enabled internally when needed, not manually installed
+ */
 export const builtinMCPServers: BuiltinMCPServer[] = [
   {
     id: nanoid(),