Feature: MCP server & tool display customization (color, name, icon)

Problem

MCP tools are second-class citizens visually compared to agents. Agents get colored badges, custom names, and distinct visual identity in the CLI. MCP tools render as plain, uncolored tool calls with raw server/tool names like mcp__gemini-research__gemini_search. For users with multiple MCP servers (8+ in my setup), the terminal becomes a wall of visually identical tool calls that are hard to scan.

Current state:

• Agent adversarial-hunter renders with a red-colored badge and bold name
• MCP tool mcp__gemini-research__gemini_search renders as plain text with no color, no icon, and a name optimized for machines, not humans

This matters because MCP servers are increasingly central to Claude Code workflows. Users build entire toolchains around MCP — database access, browser automation, research, code navigation, design systems. These deserve the same visual polish as agents.

Proposal: display configuration block in .mcp.json

Add an optional display object to MCP server configurations that controls how the server and its tools render in the CLI.

Configuration Schema

// .mcp.json (or settings.json mcpServers block)
{
  "mcpServers": {
    "gemini-research": {
      "command": "node",
      "args": ["/path/to/index.js"],

      // NEW: display customization
      "display": {
        // Server-level settings (apply to all tools from this server)
        "name": "Gemini",              // Human-readable server name
        "color": "orange",             // Badge/header color
        "icon": "⚡",                  // Prefix glyph (single char)

        // Tool-level overrides
        "tools": {
          "gemini_search": {
            "name": "Quick Search",    // Override tool display name
            "icon": "🔍"              // Override icon for this tool
          },
          "gemini_deep_research": {
            "name": "Deep Research",
            "icon": "🔬"
          }
        }
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-postgres", "..."],
      "display": {
        "name": "DB",
        "color": "blue",
        "icon": "🗄",
        "tools": {
          "query": { "name": "SQL Query" }
        }
      }
    },
    "chrome-devtools": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-chrome-devtools"],
      "display": {
        "name": "Chrome",
        "color": "yellow",
        "icon": "🌐"
      }
    }
  }
}

How It Would Render

Before (current):

⏵ mcp__gemini-research__gemini_search
    query: "React server components best practices"

⏵ mcp__postgres__query
    sql: "SELECT * FROM users LIMIT 10"

⏵ mcp__chrome-devtools__take_screenshot

After (with display config):

⚡ Gemini · Quick Search                    ← colored orange
    query: "React server components best practices"

🗄 DB · SQL Query                            ← colored blue
    sql: "SELECT * FROM users LIMIT 10"

🌐 Chrome · Screenshot                      ← colored yellow

After (minimal config — just color, no display block):

⏵ gemini_search (Gemini)                    ← colored orange, existing format but colored
⏵ query (DB)                                ← colored blue
⏵ take_screenshot (Chrome)                  ← colored yellow

Detailed Specification

1. Server Display Name (display.name)

Replace the raw server identifier with a human-readable name.

• Appears in the tool header where (serverName) currently shows
• Used in permission prompts: "Allow Gemini to run Quick Search?"
• Used in the /tools list and tool search results
• If unset, falls back to current behavior (raw server name from config key)
• Max 20 characters, no newlines or control characters

2. Server Color (display.color)

Color the tool header badge/border, matching the agent color system.

Valid values: Same palette as agent colors: "red", "blue", "green", "yellow", "purple", "orange", "pink", "cyan". Plus hex values like "#8B5CF6" for custom colors.

• Applied to the tool name text in the header (same as backgroundColor treatment for agents)
• Applied to the spinner/progress indicator glyph while the tool is running
• Does NOT color the tool result body (keeps results readable)
• If unset, falls back to default "promptBorder" color (current behavior)

Implementation note: The color system already exists internally — agent colors use a valid-colors array and a color-to-theme-token map. MCP tools use the same rendering components but skip the color path. The tool header component already accepts backgroundColor and color props — it's just never populated for MCP tools.

3. Server Icon (display.icon)

Visual prefix that makes tools from different servers instantly distinguishable at a glance.

• Single character (emoji or unicode symbol) prepended to the tool header
• Replaces or renders alongside the default ⏵ pointer for MCP tools
• Shows in both active (running) and completed states
• Must be a single grapheme cluster

4. Tool Display Name (display.tools.<name>.name)

Override individual tool names for readability.

• Replaces the raw tool name (e.g., gemini_search → Quick Search)
• Server display name still shows as context: Gemini · Quick Search
• The separator · (middle dot) visually separates server from tool

Auto-formatting fallback: If display.name is set but no display.tools, automatically clean up tool names:

• gemini_search → Search (strip server name prefix if present)
• take_screenshot → Take Screenshot (title-case, replace underscores)
• query → Query (capitalize)

5. Tool Icon Override (display.tools.<name>.icon)

Override the server-level icon for specific tools that have a distinct function. Same constraints as server icon.

Integration Points

Permission Prompts

Currently: Allow mcp__gemini-research__gemini_search?
With display config: Allow ⚡ Gemini · Quick Search? (colored)

/tools Command

Group by server with display names + colors:

⚡ Gemini (gemini-research)                  ← orange header
    Quick Search        gemini_search
    Research            gemini_research
    Deep Research       gemini_deep_research

🗄 DB (postgres)                              ← blue header
    SQL Query           query

Tool Search

Display names should be searchable. Searching "gemini search" should find tools with display.name: "Gemini".

Verbose / Transcript Mode

Show both display name and raw name for debugging:

⚡ Gemini · Quick Search (mcp__gemini-research__gemini_search)

Backward Compatibility

• The display key is entirely optional — no config = exact current behavior
• Partial config works: setting only color colors the existing rendering without changing names
• The raw tool name (mcp__server__tool) remains canonical in all programmatic contexts (hooks, permissions, API)
• Display names are purely cosmetic — rendering only, not tool matching or execution

Configuration Precedence

1. Tool-level override (display.tools.<name>.*) — highest
2. Server-level default (display.*)
3. Auto-formatting (if display.name is set but no display.tools)
4. Raw names (current behavior) — lowest

Phasing Suggestion

Phase 1 (highest value, smallest change):

• display.color — wire MCP tools into the existing agent color system
• display.name — server display name in tool headers

Phase 2:

• display.tools.<name>.name — tool display name overrides
• Auto-formatting fallback for tool names

Phase 3:

• display.icon — server and tool icon prefixes
• /tools command integration
• Permission prompt integration

Technical Context

Explored the CLI source (cli.js from the npm package) and found the infrastructure already exists:

• Agent colors flow through agentDef.color → session state → Ink <Text backgroundColor={themeToken}>. MCP tools use the same rendering components but skip the color path.
• The tool header component already accepts backgroundColor and color props — never populated for MCP tools.
• MCP tool name parsing already splits mcp__server__tool into parts. Adding a display name lookup there would be clean.
• MCP tools go through a generic registration path. Adding a displayConfig property read from .mcp.json during server init would thread through naturally.

Motivation

1. Multi-server workflows: 5-10 MCP servers need visual differentiation. Color-coding makes interleaved tool calls scannable.
2. Team conventions: Shared .mcp.json in repos standardizes display names across developers.
3. Agent parity: Agents already have colors and display names. MCP tools doing equivalent work should look equivalent.
4. Accessibility: Color differentiation helps users quickly identify which system is being called in fast-scrolling output.
5. Ecosystem maturity: Display customization signals MCP is a first-class integration path.