Skip to content

Commit 8ebf59f

Browse files
author
LittleCoinCoin
committed
docs(cli): add host labels to configure command help
Added explicit [hosts: ...] labels to every argument in 'hatch mcp configure -h' output to clearly indicate which MCP hosts each option applies to. Examples: - [hosts: all] for universal arguments - [hosts: gemini, codex] for shared tool filtering options - [hosts: codex] for Codex-specific fields This improves CLI discoverability and reduces user confusion about host-specific argument applicability.
1 parent 627a556 commit 8ebf59f

File tree

2 files changed

+61
-64
lines changed

2 files changed

+61
-64
lines changed

‎docs/articles/users/CLIReference.md‎

Lines changed: 30 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -395,35 +395,35 @@ Syntax:
395395

396396
`hatch mcp configure <server-name> --host <host> (--command CMD | --url URL) [--args ARGS] [--env-var ENV] [--header HEADER] [--dry-run] [--auto-approve] [--no-backup]`
397397

398-
| Argument / Flag | Type | Description | Default |
399-
|---:|---|---|---|
400-
| `server-name` | string (positional) | Name of the MCP server to configure | n/a |
401-
| `--host` | string | Target host platform (claude-desktop, cursor, etc.) | n/a |
402-
| `--command` | string | Command to execute for local servers (mutually exclusive with --url) | none |
403-
| `--url` | string | URL for remote MCP servers (mutually exclusive with --command) | none |
404-
| `--http-url` | string | HTTP streaming endpoint URL (Gemini only) | none |
405-
| `--args` | string | Arguments for MCP server command (only with --command) | none |
406-
| `--env-var` | string | Environment variables format: KEY=VALUE (can be used multiple times) | none |
407-
| `--header` | string | HTTP headers format: KEY=VALUE (only with --url) | none |
408-
| `--timeout` | int | Request timeout in milliseconds (Gemini) | none |
409-
| `--trust` | flag | Bypass tool call confirmations (Gemini) | false |
410-
| `--cwd` | string | Working directory for stdio transport (Gemini) | none |
411-
| `--include-tools` | multiple | Tool allowlist - only these tools will be available (Gemini). Space-separated values. | none |
412-
| `--exclude-tools` | multiple | Tool blocklist - these tools will be excluded (Gemini). Space-separated values. | none |
413-
| `--env-file` | string | Path to environment file (Cursor, VS Code, LM Studio) | none |
414-
| `--input` | multiple | Input variable definitions format: type,id,description[,password=true] (VS Code) | none |
415-
| `--disabled` | flag | Disable the MCP server (Kiro) | false |
416-
| `--auto-approve-tools` | multiple | Tool names to auto-approve (Kiro). Can be used multiple times. | none |
417-
| `--disable-tools` | multiple | Tool names to disable (Kiro). Can be used multiple times. | none |
418-
| `--env-vars` | multiple | Environment variable names to whitelist/forward (Codex). Can be used multiple times. | none |
419-
| `--startup-timeout` | int | Server startup timeout in seconds (Codex, default: 10) | none |
420-
| `--tool-timeout` | int | Tool execution timeout in seconds (Codex, default: 60) | none |
421-
| `--enabled` | flag | Enable the MCP server (Codex) | false |
422-
| `--bearer-token-env-var` | string | Name of env var containing bearer token for Authorization header (Codex) | none |
423-
| `--env-header` | multiple | HTTP header from env var format: KEY=ENV_VAR_NAME (Codex). Can be used multiple times. | none |
424-
| `--dry-run` | flag | Preview configuration without applying changes | false |
425-
| `--auto-approve` | flag | Skip confirmation prompts | false |
426-
| `--no-backup` | flag | Skip backup creation before configuration | false |
398+
| Argument / Flag | Hosts | Type | Description | Default |
399+
|---:|---|---|---|---|
400+
| `server-name` | all | string (positional) | Name of the MCP server to configure | n/a |
401+
| `--host` | all | string | Target host platform (claude-desktop, cursor, etc.) | n/a |
402+
| `--command` | all | string | Command to execute for local servers (mutually exclusive with --url) | none |
403+
| `--url` | all except Claude Desktop/Code | string | URL for remote MCP servers (mutually exclusive with --command) | none |
404+
| `--http-url` | gemini | string | HTTP streaming endpoint URL | none |
405+
| `--args` | all | string | Arguments for MCP server command (only with --command) | none |
406+
| `--env-var` | all | string | Environment variables format: KEY=VALUE (can be used multiple times) | none |
407+
| `--header` | all except Claude Desktop/Code | string | HTTP headers format: KEY=VALUE (only with --url) | none |
408+
| `--timeout` | gemini | int | Request timeout in milliseconds | none |
409+
| `--trust` | gemini | flag | Bypass tool call confirmations | false |
410+
| `--cwd` | gemini, codex | string | Working directory for stdio transport | none |
411+
| `--include-tools` | gemini, codex | multiple | Tool allowlist / enabled tools. Space-separated values. | none |
412+
| `--exclude-tools` | gemini, codex | multiple | Tool blocklist / disabled tools. Space-separated values. | none |
413+
| `--env-file` | cursor, vscode, lmstudio | string | Path to environment file | none |
414+
| `--input` | vscode | multiple | Input variable definitions format: type,id,description[,password=true] | none |
415+
| `--disabled` | kiro | flag | Disable the MCP server | false |
416+
| `--auto-approve-tools` | kiro | multiple | Tool names to auto-approve. Can be used multiple times. | none |
417+
| `--disable-tools` | kiro | multiple | Tool names to disable. Can be used multiple times. | none |
418+
| `--env-vars` | codex | multiple | Environment variable names to whitelist/forward. Can be used multiple times. | none |
419+
| `--startup-timeout` | codex | int | Server startup timeout in seconds (default: 10) | none |
420+
| `--tool-timeout` | codex | int | Tool execution timeout in seconds (default: 60) | none |
421+
| `--enabled` | codex | flag | Enable the MCP server | false |
422+
| `--bearer-token-env-var` | codex | string | Name of env var containing bearer token for Authorization header | none |
423+
| `--env-header` | codex | multiple | HTTP header from env var format: KEY=ENV_VAR_NAME. Can be used multiple times. | none |
424+
| `--dry-run` | all | flag | Preview configuration without applying changes | false |
425+
| `--auto-approve` | all | flag | Skip confirmation prompts | false |
426+
| `--no-backup` | all | flag | Skip backup creation before configuration | false |
427427

428428
**Behavior**:
429429

@@ -518,7 +518,7 @@ Configure MCP server 'my-server' on host 'kiro'? [y/N]: y
518518
**Example - Codex Configuration with Timeouts and Tool Filtering**:
519519

520520
```bash
521-
$ hatch mcp configure context7 --host codex --command npx --args "-y" --args "@upstash/context7-mcp" --env-vars PATH --env-vars HOME --startup-timeout 15 --tool-timeout 120 --enabled --include-tools read --include-tools write --exclude-tools delete
521+
$ hatch mcp configure context7 --host codex --command npx --args "-y" "@upstash/context7-mcp" --env-vars PATH --env-vars HOME --startup-timeout 15 --tool-timeout 120 --enabled --include-tools read write --exclude-tools delete
522522

523523
Server 'context7' created for host 'codex':
524524
name: UPDATED None --> 'context7'

‎hatch/cli_hatch.py‎

Lines changed: 31 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -844,13 +844,6 @@ def handle_mcp_configure(
844844
omni_config_data["disabledTools"] = disable_tools
845845

846846
# Host-specific fields (Codex)
847-
env_vars = getattr(args, 'env_vars', None)
848-
startup_timeout = getattr(args, 'startup_timeout', None)
849-
tool_timeout = getattr(args, 'tool_timeout', None)
850-
enabled = getattr(args, 'enabled', None)
851-
bearer_token_env_var = getattr(args, 'bearer_token_env_var', None)
852-
env_header = getattr(args, 'env_header', None)
853-
854847
if env_vars is not None:
855848
omni_config_data["env_vars"] = env_vars
856849
if startup_timeout is not None:
@@ -1602,133 +1595,137 @@ def main():
16021595
mcp_configure_parser = mcp_subparsers.add_parser(
16031596
"configure", help="Configure MCP server directly on host"
16041597
)
1605-
mcp_configure_parser.add_argument("server_name", help="Name for the MCP server")
1598+
mcp_configure_parser.add_argument(
1599+
"server_name", help="Name for the MCP server [hosts: all]"
1600+
)
16061601
mcp_configure_parser.add_argument(
16071602
"--host",
16081603
required=True,
1609-
help="Host platform to configure (e.g., claude-desktop, cursor)",
1604+
help="Host platform to configure (e.g., claude-desktop, cursor) [hosts: all]",
16101605
)
16111606

16121607
# Create mutually exclusive group for server type
16131608
server_type_group = mcp_configure_parser.add_mutually_exclusive_group()
16141609
server_type_group.add_argument(
16151610
"--command",
16161611
dest="server_command",
1617-
help="Command to execute the MCP server (for local servers)",
1612+
help="Command to execute the MCP server (for local servers) [hosts: all]",
16181613
)
16191614
server_type_group.add_argument(
1620-
"--url", help="Server URL for remote MCP servers (SSE transport)"
1615+
"--url", help="Server URL for remote MCP servers (SSE transport) [hosts: all except claude-desktop, claude-code]"
16211616
)
16221617
server_type_group.add_argument(
1623-
"--http-url", help="HTTP streaming endpoint URL (Gemini only)"
1618+
"--http-url", help="HTTP streaming endpoint URL [hosts: gemini]"
16241619
)
16251620

16261621
mcp_configure_parser.add_argument(
16271622
"--args",
16281623
nargs="*",
1629-
help="Arguments for the MCP server command (only with --command)",
1624+
help="Arguments for the MCP server command (only with --command) [hosts: all]",
16301625
)
16311626
mcp_configure_parser.add_argument(
1632-
"--env-var", action="append", help="Environment variables (format: KEY=VALUE)"
1627+
"--env-var",
1628+
action="append",
1629+
help="Environment variables (format: KEY=VALUE) [hosts: all]",
16331630
)
16341631
mcp_configure_parser.add_argument(
16351632
"--header",
16361633
action="append",
1637-
help="HTTP headers for remote servers (format: KEY=VALUE, only with --url)",
1634+
help="HTTP headers for remote servers (format: KEY=VALUE, only with --url) [hosts: all except claude-desktop, claude-code]",
16381635
)
16391636

16401637
# Host-specific arguments (Gemini)
16411638
mcp_configure_parser.add_argument(
1642-
"--timeout", type=int, help="Request timeout in milliseconds (Gemini)"
1639+
"--timeout", type=int, help="Request timeout in milliseconds [hosts: gemini]"
16431640
)
16441641
mcp_configure_parser.add_argument(
1645-
"--trust", action="store_true", help="Bypass tool call confirmations (Gemini)"
1642+
"--trust", action="store_true", help="Bypass tool call confirmations [hosts: gemini]"
16461643
)
16471644
mcp_configure_parser.add_argument(
1648-
"--cwd", help="Working directory for stdio transport (Gemini)"
1645+
"--cwd", help="Working directory for stdio transport [hosts: gemini, codex]"
16491646
)
16501647
mcp_configure_parser.add_argument(
16511648
"--include-tools",
16521649
nargs="*",
1653-
help="Tool allowlist - only these tools will be available (Gemini)",
1650+
help="Tool allowlist / enabled tools [hosts: gemini, codex]",
16541651
)
16551652
mcp_configure_parser.add_argument(
16561653
"--exclude-tools",
16571654
nargs="*",
1658-
help="Tool blocklist - these tools will be excluded (Gemini)",
1655+
help="Tool blocklist / disabled tools [hosts: gemini, codex]",
16591656
)
16601657

16611658
# Host-specific arguments (Cursor/VS Code/LM Studio)
16621659
mcp_configure_parser.add_argument(
1663-
"--env-file", help="Path to environment file (Cursor, VS Code, LM Studio)"
1660+
"--env-file", help="Path to environment file [hosts: cursor, vscode, lmstudio]"
16641661
)
16651662

16661663
# Host-specific arguments (VS Code)
16671664
mcp_configure_parser.add_argument(
16681665
"--input",
16691666
action="append",
1670-
help="Input variable definitions in format: type,id,description[,password=true] (VS Code)",
1667+
help="Input variable definitions in format: type,id,description[,password=true] [hosts: vscode]",
16711668
)
16721669

16731670
# Host-specific arguments (Kiro)
16741671
mcp_configure_parser.add_argument(
16751672
"--disabled",
16761673
action="store_true",
1677-
help="Disable the MCP server (Kiro)"
1674+
help="Disable the MCP server [hosts: kiro]"
16781675
)
16791676
mcp_configure_parser.add_argument(
16801677
"--auto-approve-tools",
16811678
action="append",
1682-
help="Tool names to auto-approve without prompting (Kiro)"
1679+
help="Tool names to auto-approve without prompting [hosts: kiro]"
16831680
)
16841681
mcp_configure_parser.add_argument(
16851682
"--disable-tools",
16861683
action="append",
1687-
help="Tool names to disable (Kiro)"
1684+
help="Tool names to disable [hosts: kiro]"
16881685
)
16891686

16901687
# Codex-specific arguments
16911688
mcp_configure_parser.add_argument(
16921689
"--env-vars",
16931690
action="append",
1694-
help="Environment variable names to whitelist/forward (Codex)"
1691+
help="Environment variable names to whitelist/forward [hosts: codex]"
16951692
)
16961693
mcp_configure_parser.add_argument(
16971694
"--startup-timeout",
16981695
type=int,
1699-
help="Server startup timeout in seconds (Codex, default: 10)"
1696+
help="Server startup timeout in seconds (default: 10) [hosts: codex]"
17001697
)
17011698
mcp_configure_parser.add_argument(
17021699
"--tool-timeout",
17031700
type=int,
1704-
help="Tool execution timeout in seconds (Codex, default: 60)"
1701+
help="Tool execution timeout in seconds (default: 60) [hosts: codex]"
17051702
)
17061703
mcp_configure_parser.add_argument(
17071704
"--enabled",
17081705
action="store_true",
1709-
help="Enable the MCP server (Codex)"
1706+
help="Enable the MCP server [hosts: codex]"
17101707
)
17111708
mcp_configure_parser.add_argument(
17121709
"--bearer-token-env-var",
17131710
type=str,
1714-
help="Name of environment variable containing bearer token for Authorization header (Codex)"
1711+
help="Name of environment variable containing bearer token for Authorization header [hosts: codex]"
17151712
)
17161713
mcp_configure_parser.add_argument(
17171714
"--env-header",
17181715
action="append",
1719-
help="HTTP header from environment variable in KEY=ENV_VAR_NAME format (Codex)"
1716+
help="HTTP header from environment variable in KEY=ENV_VAR_NAME format [hosts: codex]"
17201717
)
17211718

17221719
mcp_configure_parser.add_argument(
17231720
"--no-backup",
17241721
action="store_true",
1725-
help="Skip backup creation before configuration",
1722+
help="Skip backup creation before configuration [hosts: all]",
17261723
)
17271724
mcp_configure_parser.add_argument(
1728-
"--dry-run", action="store_true", help="Preview configuration without execution"
1725+
"--dry-run", action="store_true", help="Preview configuration without execution [hosts: all]"
17291726
)
17301727
mcp_configure_parser.add_argument(
1731-
"--auto-approve", action="store_true", help="Skip confirmation prompts"
1728+
"--auto-approve", action="store_true", help="Skip confirmation prompts [hosts: all]"
17321729
)
17331730

17341731
# Remove MCP commands (object-action pattern)

0 commit comments

Comments
 (0)