MCPEz (Proxy Aggregator) MCP server

MCPez is a web-based management platform designed to simplify the definition, configuration, management, and monitoring of backend services such as AI models, local scripts, or remote APIs. It exposes these services through standardized proxy interfaces (SSE or STDIO), making them easy to integrate and use by other applications, particularly AI agents that need to call tools.

Installation

Prerequisites

• Docker and Docker Compose (recommended)

Using Docker

1. Build the Docker image:

   docker build -t MCPez .
   

2. Run the Docker container:

   docker run -d -p 8088:80 --name MCPez-instance -v MCPez_data:/data MCPez
   

   • -d: Run in background mode
   • -p 8088:80: Map host port 8088 to container port 80 (Nginx default port). You can change the host port as needed.
   • --name MCPez-instance: Name for the container
   • -v MCPez_data:/data: Create a Docker volume to persist SQLite database and service configurations

Accessing the Web UI

Open your browser and navigate to http://localhost:8088 (or your specified host port).

Usage Guide

Managing Services (Main Interface)

The main interface (index.html) provides an overview of all your applications and their status:

1. View Applications: See all created applications and their current status
2. Search: Filter applications by name
3. Control Services: Start or stop STDIO-type services with a single click
4. Edit Services: Click "Edit Service" to modify an existing application
5. View Status: Check detailed information about running services
6. Create New: Click "New Service" to create a new application

Creating and Editing Applications

Access the application editor (edit.html) to create or modify applications:

1. Create New: Navigate directly to edit.html
2. Edit Existing: Click "Edit Service" from the main page or access via edit.html?id=<app_id>
3. Application Details: Set the application name and description
4. Configuration Management:
   • Import/Export: Use JSON files to import or export application configurations
   • Templates: Select from pre-saved tool templates to add service configurations

Configuring Services

Within the application editor:

1. Add Services: Click the "MCP" button to add a new server configuration
2. Service Types:
   • SSE: Proxy remote HTTP SSE services by configuring Base URL and Headers
   • STDIO: Proxy local command-line processes by configuring execution commands, arguments, and environment variables
3. Save Templates: Save well-configured services as templates for future reuse
4. JSON Preview: View the real-time JSON configuration of your application
5. Save Changes: Click the "Save Configuration" button in the top-right corner

Using the AI Playground

The AI Playground (chat.html) allows you to test your configured services with AI models:

1. Configure Settings: Click the gear icon in the top-right corner to:
   • Set up AI model provider (API Key, Base URL, model name)
   • Configure MCP server address (typically http://localhost:8088/mcp/<app_id>/sse)
2. Interact: Chat with the AI model in the interface
3. Test Tool Calls: If your AI model supports Tool/Function Calling, it will be able to use the services you've configured in MCPez

Key Features

• Web User Interface: Intuitive interface for managing applications and services
• Multiple Service Types: Support for both SSE and STDIO services
• Configuration Management: Import/export configurations and save templates
• Service Status Management: Monitor and control your services
• AI Playground: Test AI and tool interactions in a convenient chat interface
• Docker Support: Easy containerized deployment

Advanced Features

Service Configuration Options

• SSE Services:

  • Base URL
  • Custom Headers
  • Authentication settings

• STDIO Services:

  • Command to execute
  • Command arguments
  • Environment variables
  • Working directory

Template Management

For frequently used service configurations:

1. Configure a service with all required parameters
2. Click "Save as Template"
3. Give the template a meaningful name
4. Use the template when creating new services by selecting it from the template library

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "mcpez" '{"command":"docker","args":["run","-p","8088:80","--name","MCPez-instance","-v","MCPez_data:/data","MCPez"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "mcpez": {
            "command": "docker",
            "args": [
                "run",
                "-p",
                "8088:80",
                "--name",
                "MCPez-instance",
                "-v",
                "MCPez_data:/data",
                "MCPez"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "mcpez": {
            "command": "docker",
            "args": [
                "run",
                "-p",
                "8088:80",
                "--name",
                "MCPez-instance",
                "-v",
                "MCPez_data:/data",
                "MCPez"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect