Profile Overlays · mcp2cli

Customize how server capabilities appear in the CLI — rename commands, hide internal tools, group related capabilities, and rename flags — without modifying the server.

Overview

A profile overlay is an optional YAML section in your config that transforms the auto-generated CLI surface:

# In your config YAML (e.g., configs/email.yaml)
profile:
  display_name: "Email CLI"
  aliases:
    long-running-operation: lro         # Rename a command
    get-tiny-image: image
    echo: ping                          # "echo" command becomes "ping"
    create.payload: object              # Rename grouped: "create payload" → "create object"
  hide:
    - debug-tool                        # Hide from help and ls
    - internal-probe
  groups:
    mail:                               # Custom grouping
      - send
      - reply
      - draft-create
  flags:
    echo:
      message: msg                      # Rename --message to --msg
  resource_verb: fetch                  # Use "fetch" instead of "get"

Features

Command Aliases

Rename commands to shorter or more intuitive names:

profile:
  aliases:
    long-running-operation: lro
    get-tiny-image: image

Before: email long-running-operation --duration 60 After: email lro --duration 60

For grouped commands, use dot notation:

profile:
  aliases:
    create.payload: object              # "create payload" → "create object"

Hide Commands

Remove commands from help output and ls listings:

profile:
  hide:
    - debug-tool
    - internal-probe

Hidden commands are not visible in --help or ls, but can still be called directly by the original name through the static bridge fallback.

Custom Groups

Override the default dotted-name grouping with explicit groups:

profile:
  groups:
    mail:
      - send
      - reply
      - draft-create
    admin:
      - user-create
      - user-delete

This creates email mail send, email mail reply, etc. regardless of the original tool names.

Flag Aliases

Rename flags on specific commands:

profile:
  flags:
    echo:
      message: msg                      # --message → --msg
    deploy:
      environment: env                  # --environment → --env

Resource Verb

Change the verb used for direct resource reads:

profile:
  resource_verb: fetch                  # "get" → "fetch"

Before: email get demo://resource/readme.md After: email fetch demo://resource/readme.md

Display Name

Customize the name shown in --help banners:

profile:
  display_name: "Acme Production CLI"

How Overlays Are Applied

graph LR
    A["Server Discovery<br/>tools, resources, prompts"] --> B["Raw CommandManifest"]
    B --> C["Apply Profile Overlay"]
    C --> D["Final CLI Surface"]

    style C fill:#f9f,stroke:#333

The overlay is applied after the manifest is built from discovery, transforming the command tree in this order:

Aliases — rename commands and grouped subcommands
Hide — remove entries from the visible manifest
Groups — re-parent commands into custom groups
Flags — rename flags on specific commands
Resource verb — adjust the resource read command name

Full Example

Given a server with these tools:

send, reply, draft.create, labels.add,
get-tiny-image, long-running-operation, debug-internal, echo

And this profile:

profile:
  display_name: "Acme Mail CLI"
  aliases:
    long-running-operation: lro
    get-tiny-image: image
    echo: ping
  hide:
    - debug-internal
  flags:
    echo:
      message: msg
  resource_verb: fetch

The CLI becomes:

email send --to user@example.com         # Tool: send
email reply --thread-id 123              # Tool: reply
email draft create --subject "New"       # Grouped by dot notation
email labels add --name urgent           # Grouped by dot notation
email image                               # Aliased from get-tiny-image
email lro --duration 60                   # Aliased from long-running-operation
email ping --msg hello                    # Aliased echo→ping, flag message→msg
email fetch demo://resource/readme.md     # resource_verb changed to fetch
# debug-internal is hidden from help/ls