CLI Documentation

Overview

mcpsx 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, mcpsx 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, mcpsx 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

npm install -g mcpsx

npx @mcpsx

Usage

The CLI can be accessed using any of these commands:

• mcp (primary command)
• mcpsx (extended alias)

# Show help mcpsx help # Start MCP mcpsx run # Start with specific tools mcpsx run --tool="sleep" mcpsx run --tools="python,pytorch,predict" # Tool group management mcpsx groups add "python-stack" --tools="python,pytorch,huggingface" mcpsx run --tools="python-stack" # Add a new MCP configuration mcpsx add "My Server" --command "node" --args "server.js" # List MCP configurations mcpsx list # Remove an MCP configuration mcpsx remove "My Server" # Use a specific MCP configuration mcpsx use "My Server"

Key Features

mcpsx 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.

mcpsx stdio [options]

Options:

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

Examples:

# Load all servers and tools mcpsx run # Load only the 'sleep' tool mcpsx run --tool="sleep" # Load multiple tools mcpsx run --tools="python,pytorch" # Load specific tools mcpsx run --tools="predict,generate" # Use a tool group mcpsx run --tools="python-stack"

groups

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

mcpsx groups <command>

Subcommands:

groups add

Create a new tool group.

mcpsx groups add <n> --tools="tool1,tool2,..."

Example:

# Create a 'python-stack' group containing multiple tools mcpsx groups add "python-stack" --tools="python,pytorch,huggingface" # Create a 'favorites' group mcpsx groups add "favorites" --tools="openai,anthropic"

groups remove

Remove a tool group.

mcpsx groups remove <n>

groups list

List all tool groups.

mcpsx groups list

Tool Groups

Groups are at the core of mcpsx's efficiency strategy. They allow you to create collections of mcpsx 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 mcpsx groups add "ai-models" --tools="openai,anthropic,llama" mcpsx groups add "data-tools" --tools="pandas,numpy,sklearn" # Use a specific group mcpsx run --tools="ai-models" # Combine groups with individual tools mcpsx run --tools="ai-models,custom-tool,predict"

add

Add a new MCP configuration.

mcpsx add <n> [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:

mcpsx add "GPT Server" --command "node" --args "server.js,--port=3000" --env "API_KEY=abc123,DEBUG=true"

remove

Remove an MCP configuration.

mcpsx remove <n>

list

List all MCP configurations.

mcpsx list

use

Use a specific MCP configuration.

mcpsx use <n>

help

Display help information.

mcpsx help

Configuration

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

Token Optimization Strategy

One of mcpsx'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, mcpsx lets you provide just the tools needed for the current context, resulting in more efficient and cost-effective AI interactions.