Disambiguate /add-mcp and /add-mcp-server slash commands

[vkodithala]

Summary

The /add-mcp and /add-mcp-server slash commands are easy to confuse because their names are nearly identical but they perform different workflows. Warp should better disambiguate the command names, descriptions, or presentation so users can tell whether they are opening MCP settings or editing file-based MCP configuration.

Problem

A user noted that /add-mcp and /add-mcp-server sound like variants of the same command, but they currently target different MCP setup paths:

• /add-mcp configures regular MCP servers directly in Warp's MCP settings and opens the settings flow.
• /add-mcp-server is an agent skill that edits Warp's file-based MCP configuration, e.g. .mcp.json.

Because both commands use very similar naming around "add MCP server," users may select the wrong one when trying to add an MCP server. This is especially confusing now that Warp has both settings-managed MCP servers and file-based MCP configs.

Expected behavior

Users should be able to distinguish the two workflows from the slash-command menu before invoking either command. The command names, descriptions, categorization, or other UI affordances should make it clear which command opens Warp's MCP settings and which command edits file-based MCP configuration.

Actual behavior

The commands are named similarly enough that their different destinations are not obvious:

• /add-mcp appears as a product slash command for adding an MCP server through settings.
• /add-mcp-server appears as an agent skill for adding an MCP server to Warp's file-based configuration.

The distinction between "settings-managed MCP server" and "file-based MCP config" is easy to miss from the command names alone.

Reproduction steps or desired workflow

1. Open the slash-command menu.
2. Search for MCP-related add commands.
3. Observe /add-mcp and /add-mcp-server appearing as similarly named options.
4. Try to infer which command opens MCP settings versus which command edits .mcp.json file-based configuration.

Desired workflow: the user can confidently choose the correct MCP setup path without knowing the implementation distinction ahead of time.

Artifacts

None attached.

Warp version

v0.2026.04.30.08.57.dev_00

Operating system

macOS 26.4.1 (build 25E253)

Possible source references

• app/src/search/slash_command_menu/static_commands/commands.rs: defines the static /add-mcp command with description Add new MCP server and registers it in the slash-command registry.
• app/src/terminal/input/slash_commands/mod.rs: executes /add-mcp by dispatching TerminalAction::OpenAddMCPPane, which opens the settings-managed MCP flow.
• resources/bundled/skills/add-mcp-server/SKILL.md: defines the add-mcp-server skill and describes editing global or project .mcp.json file-based MCP configuration.
• app/src/settings_view/ai_page.rs: MCP settings copy distinguishes managed MCP servers from file-based MCP detection, which may be relevant context for clearer command wording.

[oz-for-oss]

@vkodithala

Here's what I found while triaging this issue:

Thanks for flagging this. The current slash-command menu can surface both product commands and skills for MCP setup, so this appears to be a valid UX clarity gap rather than an environment-specific issue.

Maintainer details

I concluded that the issue reports a reproducible UX ambiguity where the slash-command menu can show similarly named MCP setup entries that lead to different workflows..

Triage

This looks like an actionable UX clarity enhancement rather than an environment-specific bug. The report's core observation is supported by the current implementation: the slash-command menu can include both static product commands and bundled skills for the same query, and the two MCP add flows have overlapping names/descriptions while routing to different setup paths.

Evidence

• app/src/search/slash_command_menu/static_commands/commands.rs defines the static /add-mcp command with the description Add new MCP server.
• app/src/terminal/input/slash_commands/mod.rs dispatches that static command to TerminalAction::OpenAddMCPPane, and app/src/terminal/view.rs handles it by opening the MCP settings edit page.
• app/src/terminal/input/slash_commands/data_source/mod.rs searches skills alongside static slash commands when skill listing and AI are enabled, so bundled skills can appear in the same slash-command result set.
• resources/bundled/skills/add-mcp-server/SKILL.md defines the add-mcp-server skill and describes adding MCP servers through native file-based config paths such as ~/.warp/.mcp.json or project .warp/.mcp.json.
• app/src/settings_view/ai_page.rs already contains settings copy that distinguishes managed MCP servers from file-based MCP detection, which may be useful source material for clearer command descriptions or grouping.

Suggested next step

Route this to the MCP/search/skills owners to decide whether to rename one command, revise descriptions, add source/type affordances in the slash-command menu, or otherwise clarify that /add-mcp opens settings-managed MCP setup while /add-mcp-server invokes a file-config-editing skill.

This is my automated analysis and may be incorrect. A maintainer will verify the details.

Powered by Oz

[oz-for-oss]

This issue has been labeled ready-to-implement and is open for contributions involving code changes. If you'd like to tackle it, feel free to open a pull request against this issue. You can also comment @oz-agent on this issue to have the bot draft an implementation PR automatically.

[vkodithala]

@oz-agent We should be disambiguating these slash commands more. Let's make a minimal UI-only change to the name and description of the /add-mcp and /add-mcp-server slash commands, so that:

• /add-mcp retains its title, but includes an enriched description "Add a new MCP server via the MCP settings page"
• /add-mcp-server retains its description, with a new skill title "agent-add-mcp"

[oz-for-oss]

@vkodithala

I'm implementing this issue with no spec context.

You can view the conversation on Warp.

I created a new draft implementation PR for this issue.

Next steps:

• Review the implementation changes in the PR.
• Complete any manual verification needed for this issue before merging.

Powered by Oz