mcp2cli

SKILL: mcp2cli

This skill enables AI agents and coding assistants to work effectively with the mcp2cli CLI tool — both as users invoking it from the terminal and as contributors editing its source code.

---

When to Activate This Skill

Use this skill when the user:

• Asks how to run a command against an MCP server from the terminal
• Wants to create a named config, symlink alias, or set an active config
• Needs to parse or transform mcp2cli --json output with jq
• Is writing a shell script or CI pipeline that calls MCP tools
• Is implementing an AI agent loop that invokes MCP tools via mcp2cli
• Is editing source files under src/
• Asks about the MCP protocol, transports, or capability discovery
• Wants to install or regenerate man pages for mcp2cli or an alias

---

Key Concepts

Two modes

Mode	When to use	How
Ad-hoc	Exploration, one-off scripts, CI	mcp2cli --url URL COMMAND or mcp2cli --stdio CMD COMMAND
Named config + alias	Daily use, multiple servers	mcp2cli config init, mcp2cli link create, then use the alias directly

Dispatch routing

• argv[0] == "mcp2cli" → host mode (config/link/use/man/daemon commands)
• argv[0] == "<alias>" → bridge mode (MCP runtime commands for that named config)
• mcp2cli <config-name> <command> → bridge mode with explicit config name

JSON output

Every command supports --json. The response envelope is:

{
  "app_id": "<alias>",
  "command": "<command>",
  "summary": "<one-line>",
  "lines": ["..."],
  "data": { ... }
}

Pipe to jq for scripting: email --json ls | jq '.data.items[].id'

---

Common Tasks

Discover what a server offers

# Ad-hoc
mcp2cli --url http://localhost:3001/mcp ls
mcp2cli --url http://localhost:3001/mcp ls --tools
mcp2cli --url http://localhost:3001/mcp ls --resources

# Named alias
email ls
email ls --prompts
email ls --filter "draft"

Call a tool

# Ad-hoc
mcp2cli --url http://localhost:3001/mcp echo --message hello

# Named alias
email send --to [email protected] --subject "Hi" --body "Hello"
email search --query "from:boss"
email reply --thread-id 123 --body "Thanks"