1xn-vmcp 0.1.7

v(irtual)MCP - Extend, Compose, Customize MCP servers

vMCP - Virtual Model Context Protocol

An open-source tool for aggregating and managing multiple MCP servers with a unified interface.

vMCP (Virtual Model Context Protocol) is an open-source platform that allows you to connect to different mcp servers, modify them and add new tools, prompts . vMCP allows user to create customised mcp servers that can be used as drop in replactement in the agent building platforms.

Highlight Features

• ✅ Flexible Proxy Server Creation: Selectively combine different MCP servers into a unified proxy server.
• 🛠️ Customizable Tools: Override tool names/descriptions and prefill tool arguments.
• ✨ Extensible Tooling: Create new tools using Python snippets or REST APIs or plain text.
• 🗣️ Programmable Prompts: Define prompts that can invoke other tools, enabling user-controlled tool chaining.
• 🔐 MCP Server Authentication: OAuth 2.0 support for MCP servers that require it
• 📊 Usage Statistics: Track and analyze vMCP usage patterns
• 🐳 Docker Ready: Official Docker images for easy deployment
• 📝 Standard Logging: Clean logging with DEBUG, INFO, WARNING, ERROR levels

🚀 Quickstart

Prerequisites

vMCP requires Python 3.10 to 3.13 and uv.

Installation

To install vMCP, run:

Option 1: Using uvx (Recommended)

uvx --with 1xn-vmcp vmcp run

Or using uv

Option 2: Using pip

pip install 1xn-vmcp
vmcp run

Option 3: Using Docker

docker pull onexn/vmcp:latest
docker run -it onexn/vmcp:latest vmcp run

This will start the vMCP server on http://localhost:8000.

🛠️ Development

Project Structure

vmcp/
├── src/vmcp/              # Main package
│   ├── backend/           # FastAPI backend
│   │   ├── mcps/          # MCP server management
│   │   ├── vmcps/         # Virtual MCP management
│   │   ├── storage/       # Database models
│   │   ├── proxy_server/  # Main app
│   │   └── utilities/     # Logging & tracing
│   └── cli/               # CLI commands
├── frontend/              # React frontend (Vite)

Setup Development Environment

# Clone the repository
git clone https://github.com/codesque16/1xn-vmcp
make build-frontend
make run

📊 Usage Examples

Creating a vMCP

This guide walks you through the process of creating and managing virtual MCP servers with vMCP. Follow these steps to get started with aggregating multiple MCP servers into a unified interface.

Step 1: Access the vMCP Home Page

After starting vMCP with vmcp run, navigate to http://localhost:8000 in your browser. The vMCP home page provides a centralized dashboard where you can manage your virtual MCP configurations

Step 2: Create a New vMCP

Click the "+ Create Your First vMCP" button to start building your virtual MCP. In the creation dialog, provide a name and description for your vMCP. A vMCP allows you to combine tools, resources, and prompts from multiple MCP servers into a single unified endpoint. You can add servers and configure tools later, so start with a descriptive name like "Coding_assistant" for a development-focused vMCP.

Step 3: Extend Your vMCP with MCP Servers

After creating your vMCP, you'll see the "Add MCP Connector" button which displays a grid of well known remote mcp servers. You can browse and add the servers to Vmcp

Step 4: Add a Custom Server

If you need to connect to a custom MCP server that's not in the community library, click "Add Custom Server" or use the custom server option. In the dialog, provide the server name, select the transport type (HTTP, SSE), enter the server URL, and optionally add environment variables and headers. This allows you to connect to any MCP-compatible server, including your own custom implementations.

Step 5: Filter and Edit Existing Tools

Once MCP servers are added to your vMCP, navigate to the "Tools" tab in the vMCP editor. Here you can view all available tools from your connected MCP servers. Use the search and filter options to find specific tools, enable or disable them, and override tool names and descriptions. You can also test individual tools or select/deselect all tools from a specific MCP server at once.

Step 6: Add Custom Tools and Prompts

In addition to tools from MCP servers, you can create custom tools and prompts directly in your vMCP. Navigate to the "Prompts" tab to create programmable prompts that can invoke other tools, enabling user-controlled tool chaining. You can define prompt parameters, descriptions, and use the @ syntax to mention params, config, tools, and resources. Similarly, you can create custom tools using Python snippets or REST APIs.

Step 7: Use Your vMCP

Once your vMCP is configured and saved, you can use it with any MCP-compatible client. Copy the vMCP URL from the editor (e.g., http://localhost:8000/private/Coding_asstistant/vmcp) and connect to it using tools like MCP Inspector or directly from AI applications like Claude, Cursor, or Copilot. The vMCP will aggregate all your selected tools, resources, and prompts into a single unified endpoint.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Running Tests

# start test mcp server and rest api server.
make test-servers

# run test with pytest
make run-tests

📄 License

vMCP is open-source software licensed under the MIT License.

🙏 Acknowledgments

📞 Support

• 🐛 Report Issues
• 📧 Email: [e-mail]

---

Made with ❤️ by the 1xn Team