Confusing "useLegacyMcpJson" property name in agent configuration

[danboldo-wq]

Checks

• I have searched github.com/aws/amazon-q-developer-cli/issues and there are no duplicates of my issue
• I have run q doctor in the affected terminal session
• I have run q restart and replicated the issue again

Operating system

macOS 15.7.0 (24G222)

Expected behaviour

The property should have a clear, non-legacy name like "useGlobalMcpJson" or "useStandardMcpJson" since this is the standard way to use global MCP server configuration.

Actual behaviour

The agent configuration uses "useLegacyMcpJson: true" to enable global MCP server configuration from ~/.aws/amazonq/mcp.json. The term "legacy" implies this is outdated functionality when it's actually the primary/standard way to configure MCP servers globally.

[chat-transcript]
Now you're back to using your **global MCP configuration** with all 7 servers (filesystem, git, sqlite, memory, brave-search, slack, amzn-mcp) instead of the specialized `amzn-builder` agent.

**What happened:**
- You were using the `amzn-builder` agent (specialized for Amazon development)
- Created a `default` agent that uses global MCP servers (`useLegacyMcpJson: true`)
- 

> so now we are using this: useLegacyMcpJson: true

Exactly! Now Q CLI is using:

**`useLegacyMcpJson: true`** means:
- Reads MCP servers from `~/.aws/amazonq/mcp.json` (your global config)
- Uses all 7 servers you configured: filesystem, git, sqlite, memory, brave-search, slack, amzn-mcp

**Previously with `amzn-builder` agent:**
- `useLegacyMcpJson: false` (default)
- Only used the `builder-mcp` server defined in the agent config
- Ignored your global MCP configuration

**Current setup:**
- Default agent with `useLegacyMcpJson: true`
- Access to all your MCP servers
- Full functionality you originally configured

The "legacy" naming is misleading - it's actually the standard way to use global MCP servers. The agent-specific MCP configuration is the newer feature for specialized workflows.

You now have the comprehensive MCP setup you wanted instead of being limited to just the Amazon builder tools.
[Tool uses: none]

> can we rename it from legacy to standard? i know it's cosmetic but when i do demos, i don't want folks to think of any q cli functionality as legacy. does that make sense? is it doable without risking errors later?

I understand the concern - "legacy" sounds outdated in demos. However, **I don't recommend changing this** because:

**Risk Assessment:**
- `useLegacyMcpJson` is a **hardcoded property name** in Q CLI's source code
- Changing it to `useStandardMcpJson` would break Q CLI - it won't recognize the property
- Q CLI would fall back to agent-specific MCP mode, losing your global servers
- Future Q CLI updates could overwrite your changes

**The property name is cosmetic** - users rarely see it:
- It's only visible in agent config files (internal)
- Not displayed in `q mcp list` or user-facing commands
- Demo audiences won't see this unless you show the config file

**Better demo approach:**
- Focus on the **functionality** ("global MCP servers")
- Avoid showing the config file internals
- Emphasize "comprehensive MCP setup" or "full MCP configuration"
- If asked, explain it as "using the standard global MCP configuration"

**Alternative:**
Add a comment in the config to clarify:
\```json
{
  "name": "default",
  "description": "Default agent using standard global MCP configuration",
  "useLegacyMcpJson": true
}
\```

The functionality is solid and modern - just the internal property name is poorly chosen by the Q CLI team. Better to work around the naming than risk breaking your setup.
[Tool uses: none]

> can we file a bug for it? customers won't like that

Absolutely! That's a great idea. Let's file a bug report for this confusing naming:
[Tool uses: report_issue]

(...truncated)

Steps to reproduce

1. Create an agent config with global MCP servers
2. Set "useLegacyMcpJson: true" to use global MCP configuration
3. Notice the confusing "legacy" terminology for what is standard functionality

Environment

<This will be visible to anyone. Do not include personal or sensitive information>

[q-details]
version = "1.16.2"
hash = "c4c80bb44cb22b6e19129ed7475f2793ff20135d"
date = "2025-09-19T01:27:56.356289Z (6d ago)"

[system-info]
os = "macOS 15.7.0 (24G222)"
chip = "Apple M2 Pro"
total-cores = 10
memory = "16.00 GB"

[environment]
cwd = "/Users/USER"
cli-path = "/Users/USER"
install-method = "toolbox"

[env-vars]
PATH = "/Users/USER/.local/bin:/Users/USER/.toolbox/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin:/Users/USER/.local/bin"
QTERM_SESSION_ID = "269eee9b69794b3da536b395d53163be"
Q_SET_PARENT_CHECK = "1"
Q_TERM = "1.16.2"
SHELL = "/bin/zsh"
TERM = "xterm-256color"
__CFBundleIdentifier = "org.tabby"

[chat-settings]


[chat-trusted_tools]
@builder-mcp/TaskeiGetTask=trusted
@builder-mcp/TaskeiGetRooms=trusted
@builder-mcp/TicketingReadActions=trusted
fs_read=trusted
execute_bash=trusted
fs_write=trusted
@builder-mcp/ReadInternalWebsites=trusted
@builder-mcp/InternalSearch=trusted
@builder-mcp/InternalCodeSearch=trusted
@builder-mcp/TaskeiListTasks=trusted

[chat-failed_request_ids]
none

[chat-context]
current_profile=amzn-builder
profile_context=none

files=none