mcp-proxy-cli

A CLI tool with server-client architecture for interacting with multiple MCP servers.

For AI Agents: See AGENTS.md for automatic server startup instructions that are loaded at the beginning of each chat session.

Overview

mcp-proxy-cli consists of two components:

1. mcp-proxy-cli-server: A background server that maintains persistent connections to MCP servers
2. mcp-proxy-cli: A CLI client for interacting with the server

The separation allows you to avoid the overhead of initializing MCP connections on every command.

Features

• 🔄 Server-client architecture - Persistent MCP connections for fast operations
• 🎯 Multi-server support - Connect to multiple MCP servers simultaneously
• 🔌 Multiple transports - Support for stdio, HTTP, and SSE connections
• ⚙️ Dual format support - Compatible with both Cursor and VS Code Copilot configurations
• 🤖 Agent Skills included - Automatic server startup in Cursor IDE
• 📦 Easy to use - Simple CLI commands for all MCP operations
• 🔒 Secure - Environment variable support for sensitive data

Installation

Via npm (Recommended)

npm install -g mcp-proxy-cli

Via npx (No installation required)

npx mcp-proxy-cli /list/servers

From Source

git clone https://github.com/yourusername/mcp-proxy-cli.git
cd mcp-proxy-cli
npm install
npm run build
npm link

Usage

1. Start the Server

mcp-proxy-cli-server start ./config.json

Optional: Specify a custom port

mcp-proxy-cli-server start ./config.json --port 3000

The server will print its URL and suggest setting an environment variable:

export MCP_PROXY_SERVER=3456

2. Use the CLI Client

List all servers

mcp-proxy-cli /list/servers

List all tools

# List tools from all servers
mcp-proxy-cli /list/tools

# List tools from a specific server
mcp-proxy-cli /list/tools --server everything

List all resources

# List resources from all servers
mcp-proxy-cli /list/resources

# List resources from a specific server
mcp-proxy-cli /list/resources --server everything

Read a resource

# Read a resource by URI
mcp-proxy-cli /resource/read "demo://resource/static/document/features.md"

# Read a resource from a specific server
mcp-proxy-cli /resource/read "demo://resource/static/document/features.md" --server everything

List all prompts

# List prompts from all servers
mcp-proxy-cli /list/prompts

# List prompts from a specific server
mcp-proxy-cli /list/prompts --server everything

Get a prompt

# Get a prompt without arguments
mcp-proxy-cli /prompt/get simple-prompt

# Get a prompt with arguments
mcp-proxy-cli /prompt/get args-prompt '{"city":"San Francisco","state":"California"}'

# Get a prompt from a specific server
mcp-proxy-cli /prompt/get simple-prompt --server everything

Call a tool

# Call a tool (auto-detect server)
mcp-proxy-cli /tool/call echo '{"message":"Hello, World!"}'

# Call a tool on a specific server
mcp-proxy-cli /tool/call echo '{"message":"Hello"}' --server everything

Stop the server

mcp-proxy-cli stop

Configuration

mcp-proxy-cli supports both Cursor and VS Code Copilot MCP configuration formats.

📖 Documentation:

• MCP_CONFIG_SCHEMAS.md - Complete schema reference and conversion guide
• SETUP_GUIDE.md - Step-by-step setup instructions for both formats

Quick Start - Cursor Format

Create a config.json file with your MCP servers:

{
  "mcpServers": {
    "everything": {
      "type": "local",
      "command": "npx",
      "tools": ["*"],
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "env": {}
    },
    "custom-server": {
      "type": "local",
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "env": {
        "CUSTOM_VAR": "value"
      }
    }
  }
}

Quick Start - VS Code Copilot Format

Create a .vscode/mcp.json file:

{
  "servers": {
    "everything": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"]
    },
    "custom-server": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "env": {
        "CUSTOM_VAR": "value"
      }
    }
  }
}

Configuration Locations

The server searches for configuration files in this priority order:

1. ~/.cursor-tutor/mcp-proxy-config.json (Cursor user config)
2. ~/.vscode/mcp.json (VS Code Copilot user config)
3. ~/.copilot/mcp-proxy-config.json (Copilot alternate location)
4. ./.cursor/mcp.json (Cursor workspace config)
5. ./.vscode/mcp.json (VS Code workspace config)
6. ./config.json (Project root)
7. ~/.mcp-proxy-config.json (User home)

Configuration Options

• type: Currently only "local" is supported (spawns a local process)
• command: The command to run (e.g., "npx", "python", "node")
• args: Array of command-line arguments
• tools (optional): Array of tool names to expose, or ["*"] for all tools. If not specified, all tools are allowed
• env: Environment variables to pass to the server process

Example with Everything Server

The Everything MCP server is a reference implementation that's perfect for testing.

1. Start the server with the included config:

mcp-proxy-cli-server start ./config.json

2. In another terminal, list available tools:

export MCP_PROXY_SERVER=3456
mcp-proxy-cli /list/tools

3. Call a tool:

mcp-proxy-cli /tool/call echo '{"message":"test"}'

Development

Run in development mode:

# Terminal 1: Start server
npm run dev:server start ./config.json

# Terminal 2: Use CLI
npm run dev:cli /list/servers

Architecture

┌─────────────┐         ┌──────────────────────┐         ┌─────────────┐
│   User      │         │  mcp-proxy-cli      │         │ MCP Server  │
│  Terminal   │ ──────> │     (Client)        │         │   (e.g.,    │
└─────────────┘         └──────────────────────┘         │ Everything) │
                                  │                       └─────────────┘
                                  │ HTTP                         ▲
                                  ▼                              │
                        ┌──────────────────────┐                │
                        │  mcp-proxy-cli-      │                │
                        │     server           │ ───────────────┘
                        │  (HTTP + MCP Host)   │    stdio/MCP
                        └──────────────────────┘

Installing the Cursor Skill

To use mcp-proxy-cli with Cursor AI agents:

# Clone or download the repository
git clone https://github.com/yourusername/mcp-proxy-cli.git

# Copy skill to your project
mkdir -p .cursor/skills
cp -r mcp-proxy-cli/.cursor/skills/mcp-proxy-cli .cursor/skills/

# Or install globally
mkdir -p ~/.cursor/skills
cp -r mcp-proxy-cli/.cursor/skills/mcp-proxy-cli ~/.cursor/skills/

The skill will be automatically discovered by Cursor and agents will know how to use mcp-proxy-cli.

Documentation

• SETUP_GUIDE.md - Step-by-step setup for Cursor and VS Code Copilot
• MCP_CONFIG_SCHEMAS.md - Complete configuration schema reference
• AGENTS.md - AI agent auto-start instructions
• PUBLISHING.md - Guide for publishing and distribution
• CHANGELOG.md - Version history and changes

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Related Projects

• Model Context Protocol - Official MCP specification
• MCP Servers - Official MCP server implementations
• Cursor - AI-first code editor
• GitHub Copilot - AI pair programmer

License

MIT - see LICENSE file for details