docs: update CLIReference

Document the --host flag in hatch package add that enables automatic
MCP server configuration on specified

Document the host-specific MCP configuration arguments:
- --http-url: HTTP streaming (Gemini)
- --timeout, --trust, --cwd: Gemini-specific options
- --include-tools, --exclude-tools: Tool filtering (Gemini)
- --env-file: Environment files (Cursor/VS Code)
- --input: Input variable definitions (VS Code)

Fixed underscores to hyphens in `--hatch-mcp-server-tag` argument

Author: LittleCoinCoin

docs/articles/users/CLIReference.md

@@ -4,6 +4,7 @@ This document is a compact reference of all Hatch CLI commands and options imple
 
 ## Table of Contents
 
+```
 - [Global options](#global-options)
 - [Commands](#commands)
   - [hatch create](#hatch-create)
@@ -17,12 +18,27 @@ This document is a compact reference of all Hatch CLI commands and options imple
     - [hatch env python](#hatch-env-python-advanced-python-environment-subcommands)
       - [hatch env python init](#hatch-env-python-init)
       - [hatch env python info](#hatch-env-python-info)
+      - [hatch env python add-hatch-mcp](#hatch-env-python-add-hatch-mcp)
       - [hatch env python remove](#hatch-env-python-remove)
       - [hatch env python shell](#hatch-env-python-shell)
   - [hatch package](#hatch-package-package-management)
     - [hatch package add](#hatch-package-add)
     - [hatch package remove](#hatch-package-remove)
     - [hatch package list](#hatch-package-list)
+    - [hatch package sync](#hatch-package-sync)
+  - [hatch mcp](#hatch-mcp)
+    - [hatch mcp configure](#hatch-mcp-configure)
+    - [hatch mcp sync](#hatch-mcp-sync)
+    - [hatch mcp remove server](#hatch-mcp-remove-server)
+    - [hatch mcp remove host](#hatch-mcp-remove-host)
+    - [hatch mcp list hosts](#hatch-mcp-list-hosts)
+    - [hatch mcp list servers](#hatch-mcp-list-servers)
+    - [hatch mcp discover hosts](#hatch-mcp-discover-hosts)
+    - [hatch mcp discover servers](#hatch-mcp-discover-servers)
+    - [hatch mcp backup list](#hatch-mcp-backup-list)
+    - [hatch mcp backup restore](#hatch-mcp-backup-restore)
+    - [hatch mcp backup clean](#hatch-mcp-backup-clean)
+```
 
 ## Global options
 
@@ -105,7 +121,7 @@ Syntax:
 | `--python-version` | string | Python version to create (e.g., `3.11`) | none (manager default) |
 | `--no-python` | flag | Do not create a Python environment (skip conda/mamba) | false |
 | `--no-hatch-mcp-server` | flag | Do not install `hatch_mcp_server` wrapper | false |
-| `--hatch_mcp_server_tag` | string | Git tag/branch for wrapper install (e.g., `dev`, `v0.1.0`) | none |
+| `--hatch-mcp-server-tag` | string | Git tag/branch for wrapper installation (e.g., `dev`, `v0.1.0`) | none |
 
 #### `hatch env remove`
 
@@ -223,7 +239,7 @@ Syntax:
 
 ### `hatch package` (package management)
 
-Top-level syntax: `hatch package <add|remove|list> ...`
+Top-level syntax: `hatch package <add|remove|list|sync> ...`
 
 #### `hatch package add`
 
@@ -241,9 +257,28 @@ Syntax:
 | `--force-download`, `-f` | flag | Force fetching even if cached | false |
 | `--refresh-registry`, `-r` | flag | Refresh registry metadata before resolving | false |
 | `--auto-approve` | flag | Automatically approve dependency installation prompts | false |
+| `--host` | string | Comma-separated list of MCP host platforms to configure (e.g., claude-desktop,cursor) | none |
 
 **Note:** Dependency installation prompts are also automatically approved in non-TTY environments (such as CI/CD pipelines) or when the `HATCH_AUTO_APPROVE` environment variable is set. See [Environment Variables](#environment-variables) for details.
 
+**MCP Host Integration:** When adding a package, if the `--host` flag is specified, Hatch will automatically configure the package's MCP servers on the specified hosts. This includes analyzing package dependencies and configuring all related MCP servers.
+
+**MCP Host Integration Examples:**
+
+```bash
+# Add package and automatically configure MCP servers on specific hosts
+hatch package add ./my_package --host claude-desktop,cursor
+
+# Add package for all available hosts
+hatch package add ./my_package --host all
+
+# Skip host configuration (no MCP servers configured)
+hatch package add ./my_package
+
+# Add with other flags and MCP configuration
+hatch package add registry_package --version 1.0.0 --env dev-env --host gemini --auto-approve
+```
+
 Examples:
 
 `hatch package add ./my_package`
@@ -289,17 +324,24 @@ Syntax:
 |---:|---|---|---|
 | `package_name` | string (positional) | Name of package whose MCP servers to sync | n/a |
 | `--host` | string | Comma-separated list of host platforms or 'all' | n/a |
-| `--env`, `-e` | string | Environment name (defaults to current) | current environment |
+| `--env`, `-e` | string | Target Hatch environment name (defaults to current) | current environment |
 | `--dry-run` | flag | Preview changes without execution | false |
 | `--auto-approve` | flag | Skip confirmation prompts | false |
-| `--no-backup` | flag | Disable default backup behavior | false |
+| `--no-backup` | flag | Disable default backup behavior of the MCP host's config file | false |
 
 Examples:
 
 `hatch package sync my-package --host claude-desktop`
 
 `hatch package sync weather-server --host claude-desktop,cursor --dry-run`
 
+# Multi-package synchronization examples
+# Sync main package AND all its dependencies:
+hatch package sync my-package --host all
+
+# Sync without creating backups
+hatch package sync my-package --host claude-desktop --no-backup
+
 ---
 
 ## Environment Variables
@@ -340,23 +382,36 @@ HATCH_AUTO_APPROVE=yes hatch package add production_package
 
 ## MCP Host Configuration Commands
 
-### `hatch mcp configure`
+### `hatch mcp`
+
+Commands subset to manage non-hatch package MCP servers.
+Top level syntax: `<hatch mcp configure|sync|remove|list|discover|backup> ...`
+
+#### `hatch mcp configure`
 
 Configure an MCP server on a specific host platform.
 
 Syntax:
 
-`hatch mcp configure <server-name> --host <host> (--command CMD | --url URL) [--args ARGS] [--env ENV] [--header HEADER] [--dry-run] [--auto-approve] [--no-backup]`
+`hatch mcp configure <server-name> --host <host> (--command CMD | --url URL) [--args ARGS] [--env-var ENV] [--header HEADER] [--dry-run] [--auto-approve] [--no-backup]`
 
 | Argument / Flag | Type | Description | Default |
 |---:|---|---|---|
 | `server-name` | string (positional) | Name of the MCP server to configure | n/a |
 | `--host` | string | Target host platform (claude-desktop, cursor, etc.) | n/a |
 | `--command` | string | Command to execute for local servers (mutually exclusive with --url) | none |
 | `--url` | string | URL for remote MCP servers (mutually exclusive with --command) | none |
-| `--args` | multiple | Arguments for MCP server command (only with --command) | none |
-| `--env` | string | Environment variables format: KEY=VALUE (can be used multiple times) | none |
+| `--http-url` | string | HTTP streaming endpoint URL (Gemini only) | none |
+| `--args` | string | Arguments for MCP server command (only with --command) | none |
+| `--env-var` | string | Environment variables format: KEY=VALUE (can be used multiple times) | none |
 | `--header` | string | HTTP headers format: KEY=VALUE (only with --url) | none |
+| `--timeout` | int | Request timeout in milliseconds (Gemini) | none |
+| `--trust` | flag | Bypass tool call confirmations (Gemini) | false |
+| `--cwd` | string | Working directory for stdio transport (Gemini) | none |
+| `--include-tools` | multiple | Tool allowlist - only these tools will be available (Gemini) | none |
+| `--exclude-tools` | multiple | Tool blocklist - these tools will be excluded (Gemini) | none |
+| `--env-file` | string | Path to environment file (Cursor, VS Code, LM Studio) | none |
+| `--input` | multiple | Input variable definitions format: type,id,description[,password=true] (VS Code) | none |
 | `--dry-run` | flag | Preview configuration without applying changes | false |
 | `--auto-approve` | flag | Skip confirmation prompts | false |
 | `--no-backup` | flag | Skip backup creation before configuration | false |
@@ -403,6 +458,37 @@ Configure MCP server 'api-server' on host 'claude-desktop'? [y/N]: y
 [SUCCESS] Successfully configured MCP server 'api-server' on host 'claude-desktop'
 ```
 
+**Example - Advanced Gemini Configuration**:
+
+```bash
+$ hatch mcp configure my-server --host gemini --command python --args server.py --timeout 30000 --trust --include-tools weather,calculator
+
+Server 'my-server' created for host 'gemini':
+  name: UPDATED None --> 'my-server'
+  command: UPDATED None --> 'python'
+  args: UPDATED None --> ['server.py']
+  timeout: UPDATED None --> 30000
+  trust: UPDATED None --> True
+  include_tools: UPDATED None --> ['weather', 'calculator']
+
+Configure MCP server 'my-server' on host 'gemini'? [y/N]: y
+[SUCCESS] Successfully configured MCP server 'my-server' on host 'gemini'
+```
+
+**Example - Remote Server Configuration**:
+
+```bash
+$ hatch mcp configure api-server --host vscode --url https://api.example.com --header Auth=token
+
+Server 'api-server' created for host 'vscode':
+  name: UPDATED None --> 'api-server'
+  url: UPDATED None --> 'https://api.example.com'
+  headers: UPDATED None --> {'Auth': 'token'}
+
+Configure MCP server 'api-server' on host 'vscode'? [y/N]: y
+[SUCCESS] Successfully configured MCP server 'api-server' on host 'vscode'
+```
+
 **Example - Dry Run Mode**:
 
 ```bash
@@ -433,7 +519,7 @@ Different MCP hosts support different configuration fields. The conversion repor
 
 When configuring a server with fields not supported by the target host, those fields are marked as UNSUPPORTED in the report and automatically excluded from the configuration.
 
-### `hatch mcp sync`
+#### `hatch mcp sync`
 
 Synchronize MCP configurations across environments and hosts.
 
@@ -452,7 +538,7 @@ Syntax:
 | `--auto-approve` | flag | Skip confirmation prompts | false |
 | `--no-backup` | flag | Skip backup creation before synchronization | false |
 
-### `hatch mcp remove server`
+#### `hatch mcp remove server`
 
 Remove an MCP server from one or more hosts.
 
@@ -468,7 +554,7 @@ Syntax:
 | `--auto-approve` | flag | Skip confirmation prompts | false |
 | `--no-backup` | flag | Skip backup creation before removal | false |
 
-### `hatch mcp remove host`
+#### `hatch mcp remove host`
 
 Remove complete host configuration (all MCP servers from the specified host).
 
@@ -483,7 +569,7 @@ Syntax:
 | `--auto-approve` | flag | Skip confirmation prompts | false |
 | `--no-backup` | flag | Skip backup creation before removal | false |
 
-### `hatch mcp list hosts`
+#### `hatch mcp list hosts`
 
 List MCP hosts configured in the current environment.
 
@@ -527,7 +613,7 @@ Available MCP Host Platforms:
 ✗ lmstudio         Not Found    /Users/user/.lmstudio/config.json
 ```
 
-### `hatch mcp list servers`
+#### `hatch mcp list servers`
 
 List MCP servers from environment with host configuration tracking information.
 
@@ -558,7 +644,7 @@ news-aggregator      news-toolkit         2.1.0      python news.py
                        claude-desktop: /Users/user/.claude/config.json (last synced: 2025-09-24T10:00:00)
 ```
 
-### `hatch mcp discover hosts`
+#### `hatch mcp discover hosts`
 
 Discover available MCP host platforms on the system.
 
@@ -580,7 +666,7 @@ Available MCP host platforms:
     Config path: ~/.vscode/config.json
 ```
 
-### `hatch mcp discover servers`
+#### `hatch mcp discover servers`
 
 Discover MCP servers in Hatch environments.
 
@@ -592,7 +678,7 @@ Syntax:
 |---:|---|---|---|
 | `--env` | string | Specific environment to discover servers in | current environment |
 
-### `hatch mcp backup list`
+#### `hatch mcp backup list`
 
 List available configuration backups.
 
@@ -605,7 +691,7 @@ Syntax:
 | `--host` | string | Filter backups by host | all hosts |
 | `--detailed` | flag | Show detailed backup information | false |
 
-### `hatch mcp backup restore`
+#### `hatch mcp backup restore`
 
 Restore host configuration from backup.
 
@@ -619,7 +705,7 @@ Syntax:
 | `--dry-run` | flag | Preview restore without executing changes | false |
 | `--auto-approve` | flag | Skip confirmation prompts | false |
 
-### `hatch mcp backup clean`
+#### `hatch mcp backup clean`
 
 Clean old backup files.