mcpz it!
Back to Home

CLI Documentation

Overview

mcpz CLI is a powerful command line interface for Model Context Protocol (MCP), designed to revolutionize how you manage, query, and interact with Model Context Protocol. At its core, mcpz enables intelligent organization of your MCP ecosystem, allowing you to create logical collections of tools that optimize both your workflow and AI model interactions.

By categorizing your tools into purpose-specific groups, mcpz significantly reduces token usage when communicating with AI models. Instead of sending all available tools to the system instruction, you can selectively include only the relevant tools for a specific task or context. This focused approach not only improves model performance by reducing distraction, but also minimizes token consumption and associated inference costs.

Installation

Install globally
npm install -g @mcpz/cli
Or use with npx
npx -y @mcpz/cli

Usage

The CLI can be accessed using any of these commands:

  • mcp (primary command)
  • mcpz (extended alias)
Basic commands
# Show help mcpz help
# Start MCP
mcpz run

# Start with specific tools
mcpz run --tool="sleep"
mcpz run --tools="python,pytorch,predict"

# Tool group management
mcpz groups add "python-stack" --tools="python,pytorch,huggingface"
mcpz run --tools="python-stack"

# Add a new MCP configuration
mcpz add "My Server" --command "node" --args "server.js"

# List MCP configurations
mcpz list

# Remove an MCP configuration
mcpz remove "My Server"

# Use a specific MCP configuration
mcpz use "My Server"

Key Features

mcpz CLI provides powerful capabilities for working with Model Context Protocol:

  1. Intelligent Tool Organization: Create logical collections of tools that can be activated selectively, minimizing token usage and improving AI focus.
  2. Run Tools: Start MCP tools individually or in combination based on your specific workflow needs.
  3. Add & Remove: Easily manage your MCP configurations from a central location.
  4. Query & List: View available servers and tools at any time for better visibility.
  5. Grouping: Create and manage groups of tools for simplified workflows and optimized model interactions.
  6. Flexible Filtering: Run specific tools or combinations to match your exact requirements while minimizing resource usage.

Commands

stdio

Start MCP over stdio. This is the main command used by the VSCode extension to communicate with MCP.

mcpz stdio [options]

Options:

  • -s, --tool <name> - Load only a specific tool
  • -S, --tools <names> - Load only specific tools (comma-separated)
  • -t, --tool <name> - Load only a specific tool
  • -T, --tools <names> - Load only specific tools (comma-separated)

Examples:

# Load all servers and tools mcpz run


# Load only the 'sleep' tool
mcpz run --tool="sleep"


# Load multiple tools
mcpz run --tools="python,pytorch"


# Load specific tools
mcpz run --tools="predict,generate"


# Use a tool group
mcpz run --tools="python-stack"

groups

Manage tool groups. Groups allow you to create collections of mcpz tools that can be used together. This is the heart of mcpz's token optimization capability, enabling you to create purpose-specific toolsets.

mcpz groups <command>

Subcommands:

groups add

Create a new tool group.

mcpz groups add <name> --tools="tool1,tool2,..."

Example:

# Create a 'python-stack' group containing multiple tools
mcpz groups add "python-stack" --tools="python,pytorch,huggingface"

# Create a 'favorites' group
mcpz groups add "favorites" --tools="openai,anthropic"

groups remove

Remove a tool group.

mcpz groups remove <name>

groups list

List all tool groups.

mcpz groups list

Tool Groups

Groups are at the core of mcpz's efficiency strategy. They allow you to create collections of mcpz tools that can be used together. This is particularly valuable for organizing related tools by project type, technology stack, or specific workflows—while significantly reducing token usage when interacting with AI models.

Groups act as "virtual MCPs" - when you reference a group name with --tools, it expands to include all tools in that group. This means you can send only the relevant tools to your AI models, improving focus and reducing token consumption.

Example workflow:

# Create groups for different use cases
mcpz groups add "ai-models" --tools="openai,anthropic,llama"
mcpz groups add "data-tools" --tools="pandas,numpy,sklearn"


# Use a specific group
mcpz run --tools="ai-models"


# Combine groups with individual tools
mcpz run --tools="ai-models,custom-tool,predict"

add

Add a new MCP configuration.

mcpz add <name> [options]

Options:

  • -c, --command <command> - Command to run the MCP server
  • -a, --args <args> - Arguments for the command (comma-separated)
  • -e, --env <env> - Environment variables (key=value,key2=value2)

Example:

mcpz add "myserver" --command "node" --args "server.js,--port=3232" --env "API_KEY=abc123,DEBUG=true"

remove

Remove an MCP configuration.

mcpz remove <name>

list

List all MCP configurations.

mcpz list

use

Use a specific MCP configuration.

mcpz use <name>

help

Display help information.

mcpz help

Configuration

mcpz CLI uses the configuration file located at ~/.mcpz/config.json. This file is shared with the MCP VSCode extension, ensuring consistent configuration across your entire development environment.

Token Optimization Strategy

One of mcpz's most powerful features is its ability to optimize token usage when interacting with AI models. By creating logical groups of tools, you can:

  • Send only relevant tools to models, reducing system instruction size
  • Create specialized toolsets for different types of tasks
  • Organize tools by project, platform, or workflow
  • Minimize token consumption and associated costs
  • Improve model focus by reducing tool-related distractions

This approach is particularly valuable when working with large numbers of tools across different domains. Instead of overwhelming your models with all available tools, mcpz lets you provide just the tools needed for the current context, resulting in more efficient and cost-effective AI interactions.