Cli Reference · mcp2cli

Complete reference for every mcp2cli command, flag, and option.

Invocation Modes

mcp2cli [--json] [--output <FORMAT>] [--timeout <SECS>] <command>
mcp2cli [--json] [--output <FORMAT>] [--timeout <SECS>] <config-name> <command>
mcp2cli --url <URL> [--json] [--timeout <SECS>] <command>
mcp2cli --stdio <COMMAND> [--env KEY=VAL]... [--json] [--timeout <SECS>] <command>
<alias> [--json] [--output <FORMAT>] [--timeout <SECS>] <command>

Global Flags

Flag	Short	Description
`--json`		Output JSON instead of human-readable text
`--output <FORMAT>`	`-o`	Output format: `human`, `json`, `ndjson`
`--timeout <SECONDS>`		Operation timeout in seconds (`0` = no timeout; overrides config)
`--non-interactive`		Fail instead of prompting for input (CI mode)
`--input-json <JSON>`		Supply elicitation answers (and `auth login` credentials) as a JSON object so prompts never block (CI mode)
`--no-telemetry`		Disable anonymous local usage telemetry for this invocation
`--url <URL>`		Ad-hoc HTTP MCP server URL (no config needed)
`--stdio <COMMAND>`		Ad-hoc stdio MCP server command (no config needed)
`--env <KEY=VALUE>`		Environment variable for `--stdio` server (repeatable)

CI / non-interactive mode

--non-interactive, --input-json, and --timeout are global and apply to every command surface (the dynamic per-server CLI and the static bridge). They make mcp2cli safe to run unattended:

--non-interactive turns any prompt (elicitation, auth login token entry) into an immediate error instead of blocking on a TTY.
--input-json '<OBJECT>' pre-supplies answers. For elicitation, the keys are the requested field names. For auth login, pass --input-json '{"bearer_token": "<token>", "account": "<optional>"}'.

email --non-interactive search --query "from:boss"
email --input-json '{"bearer_token": "tok_123"}' auth login
email --no-telemetry --timeout 30 send --to user@example.com --subject "Hi" --body "..."

Host Commands

These manage configs and aliases — no server connection required.

`config init`

Create a new named config.

mcp2cli config init --name <NAME> --app bridge \
  [--transport <stdio|streamable_http>] \
  [--endpoint <URL>] \
  [--stdio-command <CMD>] \
  [--stdio-arg <ARG>]... \
  [--force]

Flag	Required	Description
`--name <NAME>`	✅	Config name (alphanumeric, hyphens)
`--app <PROFILE>`		Application profile (default: `bridge`)
`--transport <TYPE>`		`stdio` or `streamable_http` (default: `streamable_http`)
`--endpoint <URL>`	for HTTP	Server endpoint URL
`--stdio-command <CMD>`	for stdio	Subprocess command
`--stdio-arg <ARG>`		Subprocess argument (repeat for each arg)
`--force`		Overwrite an existing config of the same name

# HTTP email server
mcp2cli config init --name email --app bridge \
  --transport streamable_http --endpoint https://mcp.example.com/email

# Local stdio reference server (the everything server speaks echo/add, not email)
mcp2cli config init --name local --app bridge \
  --transport stdio --stdio-command npx \
  --stdio-arg @modelcontextprotocol/server-everything

`config list`

List all named configs.

mcp2cli config list

`config show`

Display a named config.

mcp2cli config show --name <NAME>

`use`

Manage the active config.

mcp2cli use email          # Set active config
mcp2cli use --show         # Show current active config
mcp2cli use --clear        # Clear active config

`link create`

Create a symlink alias to mcp2cli. By default this also generates and installs a man page for the alias.

mcp2cli link create --name email \
  [--dir <PATH>] [--force] [--man-dir <PATH>] [--no-man]

Flag	Required	Description
`--name <NAME>`	✅	Alias name (also the symlink filename)
`--dir <PATH>`		Directory for the symlink (default: next to binary)
`--force`		Replace an existing symlink of the same name
`--man-dir <PATH>`		Man page install directory (default: `~/.local/share/man/man1`)
`--no-man`		Skip man page generation and installation

Reserved names: mcp2cli, config, link, use, daemon.

# Install an `email` alias bound to the active/email config
mcp2cli link create --name email
# email ls, email send, email auth login ... now dispatch to that config

`daemon`

Manage background daemon processes.

mcp2cli daemon start <CONFIG_NAME>    # Start daemon for config
mcp2cli daemon stop <CONFIG_NAME>     # Stop running daemon
mcp2cli daemon status [CONFIG_NAME]   # Check daemon status

Discovery Commands

`ls`

List server capabilities.

<alias> ls [--tools] [--resources] [--prompts] [--filter <PATTERN>] [--all]

Flag	Description
`--tools`	Show only tools
`--resources`	Show only resources
`--prompts`	Show only prompts
`--filter <PATTERN>`	Filter results by name substring
`--all`	List every item without pagination

`inspect`

Dump full server capabilities, metadata, and negotiated protocol info.

<alias> inspect

`doctor`

Run runtime health diagnostics.

<alias> doctor

Checks: transport connection, server info, auth state, cached capabilities.

`ping`

Server liveness check with latency measurement.

<alias> ping

Tool Commands

Dynamic (auto-generated)

Server tools become commands with flags from JSON Schema. With an email alias bound to an email MCP server, its tools are exposed directly (the alias already namespaces them, so there is no email. prefix on the command):

<alias> <tool-name> [--flag <value>]...

Examples against the email server:

email send --to user@example.com --subject "Hi" --body "..."   # String flags
email search --query "from:boss"                               # String flag
email draft create --subject "New draft"                       # Dotted tool (draft.create)
email reply --thread-id 123 --body "Thanks"                    # String flags
email labels add --thread-id 123 --label important             # Dotted tool (labels.add)

Flag types follow the tool’s JSON Schema — booleans become bare switches, arrays and objects take JSON values:

local echo --message hello             # String flag
local add --a 5 --b 3                  # Integer flags
<alias> deploy --tags '["a","b"]'      # Array flag (JSON)
<alias> process --include-metadata     # Boolean flag
<alias> build --config '{"opt": true}' # JSON flag

The local alias above points at a stdio @modelcontextprotocol/server-everything config — a real reference server whose tools are echo/add/etc., not email tools.

Static Bridge Fallback

<alias> tool list [--filter <PATTERN>] [--all]
<alias> tool call <TOOL_NAME> [--arg <KEY=VALUE>]... [--args-file <PATH>] [--args-json <JSON>] [--background]

Resource Commands

Read a Resource

<alias> get <URI>
<alias> <resource-verb> <URI>        # If profile.resource_verb is set

Examples against the email server:

email get mail://inbox
email get mail://thread/123

Resource Templates (auto-generated)

<alias> <template-name> [--param <value>]...
<alias> <template-name> <positional>          # Single-param templates

Static Bridge Fallback

<alias> resource list [--filter <PATTERN>] [--all]
<alias> resource read <URI>

Subscriptions

<alias> subscribe <URI>
<alias> unsubscribe <URI>

Prompt Commands

Dynamic (auto-generated)

<alias> <prompt-name> [--arg <value>]...

Static Bridge Fallback

<alias> prompt list [--filter <PATTERN>] [--all]
<alias> prompt run <PROMPT_NAME> [--arg <KEY=VALUE>]...

Auth Commands

email auth login           # Prompt for a bearer token (or read it from stdin)
email auth logout          # Clear stored credentials
email auth status          # Show current auth state

auth login reads a bearer token interactively, from a piped stdin (echo "$TOKEN" | email auth login), or from --input-json '{"bearer_token": "<token>"}'. With --non-interactive and no token available it fails fast instead of prompting.

Job Commands

<alias> jobs list                          # List all background jobs
<alias> jobs show <JOB_ID>                 # Show job details
<alias> jobs show --latest                 # Show most recent job
<alias> jobs wait <JOB_ID>                 # Block until job completes
<alias> jobs wait --latest                 # Wait for most recent job
<alias> jobs cancel <JOB_ID>              # Cancel a running job
<alias> jobs cancel --latest               # Cancel most recent job
<alias> jobs watch <JOB_ID>               # Stream job progress events
<alias> jobs watch --latest                # Watch most recent job

Logging Command

<alias> log <LEVEL>

Level	Description
`trace`	Most verbose
`debug`	Debug messages
`info`	Informational
`warn`	Warnings
`error`	Errors only

Completion Command

<alias> complete <REF_TYPE> <REF_NAME> <ARG_NAME> [CURRENT_VALUE]

Requests tab-completion values from the server.

Argument	Description
`<REF_TYPE>`	Reference type: `ref/prompt`, `ref/resource`
`<REF_NAME>`	Name of the prompt or resource
`<ARG_NAME>`	Argument name to complete
`[CURRENT_VALUE]`	Current partial input for filtering

Argument Input Methods

Multiple sources for tool arguments, merged in order (later wins):

# From file
email send --args-file ./payload.json

# From JSON string
email send --args-json '{"to": "user@example.com"}'

# From flags
email send --to user@example.com

# Combined (merged, flags override)
email send --args-file base.json --args-json '{"subject": "Hi"}' --to final@example.com

Environment Variables

Variable	Description
`MCP2CLI_CONFIG_DIR`	Override config directory
`MCP2CLI_DATA_DIR`	Override data directory
`MCP2CLI_LOGGING__LEVEL`	Override log level
`MCP2CLI_LOGGING__FORMAT`	Override log format
`MCP2CLI_SERVER__ENDPOINT`	Override server endpoint
`MCP2CLI_SERVER__TRANSPORT`	Override transport type
`MCP2CLI_DEFAULTS__OUTPUT`	Override default output format
`MCP2CLI_DEFAULTS__TIMEOUT_SECONDS`	Override default timeout

Pattern: MCP2CLI_ prefix + config path with __ as separator.

Invocation Modes

Global Flags

CI / non-interactive mode

Host Commands

config init

config list

config show

use

link create

daemon

Discovery Commands

ls

inspect

doctor

ping

Tool Commands

Dynamic (auto-generated)

Static Bridge Fallback

Resource Commands

Read a Resource

Resource Templates (auto-generated)

Static Bridge Fallback

Subscriptions

Prompt Commands

Dynamic (auto-generated)

Static Bridge Fallback

Auth Commands

Job Commands

Logging Command

Completion Command

Argument Input Methods

Environment Variables

See Also

`config init`

`config list`

`config show`

`use`

`link create`

`daemon`

`ls`

`inspect`

`doctor`

`ping`