English | 中文

MCP-UNI

MCP-UNI is a Model Context Protocol (MCP) universal server that acts as a unified gateway for connecting and managing multiple MCP servers. It provides a single HTTP endpoint to dynamically connect, disconnect, and interact with various MCP servers without requiring static configuration.

Features

• 🔌 Dynamic MCP Server Management: Connect and disconnect MCP servers at runtime

• 🌐 HTTP Server Interface: RESTful API with Server-Sent Events (SSE) support

• 🔗 Multiple Transport Support: Supports both SSE and stdio transports

• 🛠️ Tool Aggregation: Exposes all connected MCP server tools through a unified interface

• 📚 Resource Management: Access resources and resource templates from connected servers

• 💬 Prompt Management: Manage prompts across multiple MCP servers

• 🔄 Auto-retry: Built-in retry mechanism for connection failures

• 📋 Real-time Updates: Dynamic tool list updates when servers connect/disconnect

Related MCP server: Shared MCP Gateway

Architecture

MCP-UNI acts as a proxy/gateway between clients and multiple MCP servers:

Client ──HTTP/SSE──> MCP-UNI ──stdio/SSE──> MCP Server 1
                        │
                        ├─────stdio/SSE──> MCP Server 2
                        │
                        └─────stdio/SSE──> MCP Server N

Installation

Using npx (Recommended)

npx mcp-uni

From npm (Coming Soon)

npm install -g mcp-uni

From Source

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

Quick Start

Method 1: Using Configuration File (Recommended)

1. Create a configuration file (mcp-uni.config.json):

   {
     "mcpServers": {
       "everything": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-everything"],
         "env": {}
       }
     }
   }

2. Start the MCP-UNI server:

   # Using npx (no installation required)
   npx mcp-uni
   
   # With custom port
   npx mcp-uni --port 8000
   
   # With custom config file
   npx mcp-uni --config /path/to/your-config.json
   
   # Or if installed globally
   mcp-uni
   mcp-uni --port 8000

   The server will start on http://localhost:7200 (or your specified port) with SSE endpoint at /stream, and automatically connect the MCP servers defined in your configuration file.

Method 2: Manual Connection

1. Start the MCP-UNI server:

   # Using npx (no installation required)
   npx mcp-uni
   
   # With custom port
   npx mcp-uni --port 8000
   
   # Or if installed globally
   mcp-uni
   mcp-uni --port 8000

   The server will start on http://localhost:7200 (or your specified port) with SSE endpoint at /stream.

2. Connect an MCP server:

   curl -X POST http://localhost:7200/tools/connect_mcp \
     -H "Content-Type: application/json" \
     -d '{
       "name": "my-mcp-server",
       "transportConfig": {
         "type": "stdio",
         "command": "node",
         "args": ["./my-mcp-server/index.js"],
         "env": {},
         "cwd": "/path/to/server"
       }
     }'

3. List connected servers:

   curl -X POST http://localhost:7200/tools/list_mcp \
     -H "Content-Type: application/json" \
     -d '{}'

Configuration

Configuration File

MCP-UNI supports a configuration file (mcp-uni.config.json) to automatically connect MCP servers on startup. This allows you to pre-configure your MCP servers without manually connecting them each time.

Configuration File Format

{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "env": {}
    }
  }
}

Configuration File Location

• Default: mcp-uni.config.json in the current working directory

• Custom: Use --config option to specify a different path

Example Configuration Files

Multiple MCP Servers:

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {}
    },
    "everything": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "env": {}
    },
    "database": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "database_mcp_server"],
      "env": {
        "DB_URL": "sqlite:///app.db"
      },
      "cwd": "/path/to/db/server"
    }
  }
}

SSE Transport Configuration:

{
  "mcpServers": {
    "remote-server": {
      "type": "sse",
      "url": "http://example.com/sse",
      "query": {
        "param1": "value1"
      },
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  }
}

Transport Configuration

MCP-UNI supports two types of transport configurations:

SSE Transport

{
  "type": "sse",
  "url": "http://example.com/sse",
  "query": {
    "param1": "value1"
  },
  "headers": {
    "Authorization": "Bearer token"
  }
}

Stdio Transport

{
  "type": "stdio",
  "command": "python",
  "args": ["-m", "my_mcp_server"],
  "env": {
    "ENV_VAR": "value"
  },
  "cwd": "/path/to/working/directory"
}

Command Line Options

mcp-uni [options]

Options:
  -p, --port <number>    Port to listen on (default: 7200)
  -s, --stream <path>    Stream endpoint path (default: /stream)
  -c, --config <path>    Config file path (default: mcp-uni.config.json)
  -h, --help            Display help for command
  -V, --version         Display version number

Examples

# Start server on default port (7200) with default config
npx mcp-uni

# Start server on custom port
npx mcp-uni --port 8000

# Start server with custom config file
npx mcp-uni --config /path/to/my-config.json

# Start server with custom port and config
npx mcp-uni --port 8000 --config ./configs/production.json

# Start server with custom stream endpoint
npx mcp-uni --port 8000 --stream /events

# Show help
npx mcp-uni --help

# Show version
npx mcp-uni --version

API Reference

Built-in Tools

MCP-UNI provides these management tools:

connect_mcp

Connect a new MCP server to the host.

Parameters:

• name (string): Unique name for the MCP server

• transportConfig (object): Transport configuration (see above)

disconnect_mcp

Disconnect an MCP server from the host.

Parameters:

• name (string): Name of the MCP server to disconnect

list_mcp

List all currently connected MCP servers.

Parameters: None

Dynamic Tools

All tools from connected MCP servers are automatically exposed through MCP-UNI with their original names and schemas.

HTTP Endpoints

• POST /tools/{tool_name} - Execute a tool

• GET /stream - SSE endpoint for real-time updates

• GET /health - Health check endpoint

Usage Examples

Connecting Multiple Servers

# Connect a file system MCP server
curl -X POST http://localhost:7200/tools/connect_mcp \
  -H "Content-Type: application/json" \
  -d '{
    "name": "filesystem",
    "transportConfig": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {},
      "cwd": "."
    }
  }'

# Connect a database MCP server
curl -X POST http://localhost:7200/tools/connect_mcp \
  -H "Content-Type: application/json" \
  -d '{
    "name": "database",
    "transportConfig": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "database_mcp_server"],
      "env": {"DB_URL": "sqlite:///app.db"},
      "cwd": "/path/to/db/server"
    }
  }'

Using Connected Server Tools

Once servers are connected, their tools become available:

# Use filesystem server tool
curl -X POST http://localhost:7200/tools/read_file \
  -H "Content-Type: application/json" \
  -d '{"path": "/tmp/example.txt"}'

# Use database server tool
curl -X POST http://localhost:7200/tools/execute_query \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT * FROM users LIMIT 10"}'

Development

Project Structure

src/
├── index.ts              # Entry point and HTTP server setup
├── server.ts             # MCP server implementation
├── host.ts               # MCP host for managing connections
└── utils/
    ├── schema-converter.ts # JSON Schema to Zod conversion utilities
    └── utils.ts           # Utility functions

Building

npm run build

The compiled JavaScript will be output to the build/ directory.

Key Components

• McpHost (host.ts:37): Manages connections to multiple MCP servers

• createServer (server.ts:15): Creates the unified MCP server instance

• Schema Conversion (utils/schema-converter.ts): Converts JSON schemas to Zod schemas

• Transport Management (host.ts:166): Handles different transport types (SSE/stdio)

Error Handling

MCP-UNI includes robust error handling:

• Connection Retries: Automatic retry with backoff for failed connections (3 retries, 2.5s delay)

• Tool Execution: Proper error propagation from connected servers

• Graceful Cleanup: Automatic cleanup of connections on server shutdown

Requirements

• Node.js 16+ (ES modules required)

• TypeScript 5+

Dependencies

• @modelcontextprotocol/sdk: MCP SDK for client/server implementation

• mcp-proxy: HTTP proxy server for MCP protocol

• zod: Schema validation and type safety

License

MIT

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

Support

For issues and questions:

• Create an issue on GitHub

• Check existing documentation

• Review the MCP specification

MCP-UNI simplifies MCP server management by providing a unified, dynamic gateway for all your Model Context Protocol servers.