1xn-vmcp 0.1.5

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

vMCP - Virtual Model Context Protocol

A containerization platform for MCPs that lets you compose, customize, and deploy AI agent capabilities at scale.

What is vMCP?

vMCP (Virtual Model Context Protocol) transforms how you work with MCP servers by introducing containerization for AI capabilities. Instead of managing scattered MCP servers individually, vMCP lets you:

🎯 Curate with Precision: Connect to multiple MCP servers but cherry-pick only the tools, resources, and prompts you actually need 🔨 Extend with Custom Logic: Create your own tools using Python functions or REST APIs, and add custom resources and prompts 📦 Package as Containers: Bundle your curated capabilities into self-contained "virtual MCPs" (vMCPs) that can be versioned, shared, and deployed anywhere 🔌 Connect Once, Use Everywhere: Point any AI client (Claude, OpenAI, custom agents) to a single vMCP endpoint that aggregates everything

Think of vMCP as Docker for AI capabilities - where each container is a carefully crafted collection of tools, data sources, and prompts tailored for specific use cases.

Why vMCP?

The Problem Modern AI applications need access to multiple MCP servers (filesystem, GitHub, Slack, databases, etc.). Managing these connections individually leads to:

🔁 Redundant configurations across projects 🎚️ No granular control over which capabilities to expose 🚫 Difficulty standardizing agent behavior across teams 📊 No visibility into usage patterns

The Solution

vMCP provides a unified aggregation layer where you can: Multiple MCP Servers → Curate → Customize → Container → Deploy (Filesystem, GitHub, Slack) (Select tools) (Add custom) (vMCP) (AI Clients) Example: Create a "DevOps Assistant" vMCP that combines:

GitHub's create_issue and list_prs tools (but not delete_repo) Filesystem's read_file (but not write_file for safety) Your custom deploy_to_staging tool built with Python Slack's notification capabilities Custom prompts for incident response workflows

Deploy this single vMCP endpoint, and any AI agent can instantly access this curated, secure capability set.

Key Features

✅ Selective Tool Exposure: Connect to any MCP server and choose exactly which tools, resources, and prompts to include 🔨 Custom Capabilities: Build your own tools using Python functions or REST API integrations 📦 Virtual Containers: Package everything into reusable, shareable vMCP containers 🔌 Universal Compatibility: Works with stdio, HTTP, and SSE MCP transports 🔐 Authentication Support: Handle OAuth 2.0, Bearer tokens, and Basic auth for MCP servers 📊 Usage Analytics: Track tool calls, resource reads, and prompt usage patterns 🐳 Deploy Anywhere: Run locally, in Docker, or on any cloud platform 🔍 OpenTelemetry Tracing: Built-in observability for debugging and monitoring

🚀 Quickstart

Prerequisites

vMCP requires Python 3.10 to 3.13 and uv.

Installation

To install vMCP, run:

uv pip install 1xn-vmcp

Or use uvx to run directly:

uvx 1xn-vmcp run

Running vMCP

To run vMCP locally:

vmcp run

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

📖 What is vMCP?

vMCP (Virtual Model Context Protocol) is an open-source platform that allows you to:

• Aggregate Multiple MCP Servers: Connect to multiple MCP servers (stdio, HTTP, SSE) and manage them from a single interface
• Create Virtual MCPs: Combine tools, resources, and prompts from multiple servers into unified virtual endpoints. create custom tools using python function or using rest apis.
• Manage Connections: Handle MCP server authentication (OAuth, Bearer tokens, Basic auth)
• Track Usage: Monitor tool calls, resource reads, and prompt usage with built-in analytics
• Deploy Anywhere: Run locally, in Docker, or deploy to cloud platforms

Key Features

• ✅ No Authentication Required: Single local user mode for simplicity
• 🔌 MCP Protocol Support: Full support for stdio, HTTP, and SSE transports
• 🔐 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
• 🔍 OpenTelemetry Tracing: Built-in distributed tracing support
• 📝 Standard Logging: Clean logging with DEBUG, INFO, WARNING, ERROR levels

🏗️ Architecture

Components

1. MCP Servers: Individual MCP servers you connect to (e.g., filesystem, GitHub, Slack)
2. VMCPs: Virtual MCPs that aggregate multiple MCP servers
3. Storage: PostgreSQL database for configuration and stats
4. Web UI: React-based interface for managing VMCPs and connections

How it Works

┌─────────────┐
│  AI Client  │ (Claude, OpenAI, etc.)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│    vMCP     │ (Virtual MCP Endpoint)
└──────┬──────┘
       │
       ├─────► MCP Server 1 (Filesystem)
       ├─────► MCP Server 2 (GitHub)
       └─────► MCP Server 3 (Slack)

🛠️ Development

Project Structure

1xn_oss/
├── backend/               # Python backend
│   ├── src/
│   │   ├── main.py        # Application entry point
│   │   └── vmcp/          # Main package
│   │       ├── cli/       # CLI commands
│   │       ├── config.py  # Configuration
│   │       ├── data/      # Data files
│   │       ├── mcps/      # MCP server management
│   │       ├── proxy_server/ # FastAPI backend
│   │       ├── scripts/   # Utility scripts
│   │       ├── storage/   # Database models
│   │       ├── utilities/ # Logging & tracing
│   │       └── vmcps/     # Virtual MCP management
│   ├── public/            # Static files (built frontend/docs)
│   └── pyproject.toml     # Python dependencies
├── frontend/              # React frontend (Vite)
├── docs/                  # Documentation (Docusaurus)
├── docker/                # Docker configuration
└── instructions/          # Project documentation

Setup Development Environment

# Clone the repository
git clone https://github.com/vmcp/vmcp.git
cd vmcp

# Install dependencies
uv sync


# Start development server
cd src
python3 main.py --reload

Environment Variables

Create a .env file in the project root:

# Database
DATABASE_URL=postgresql://vmcp:vmcp@localhost:5432/vmcp

# Server
HOST=0.0.0.0
PORT=8000
BASE_URL=http://localhost:8000

# Logging
LOG_LEVEL=INFO

# Tracing (optional)
ENABLE_TRACING=false
OTLP_ENDPOINT=http://localhost:4317

📊 Usage Examples

Creating a vMCP

import httpx

# Create a new vMCP
response = httpx.post("http://localhost:8000/vmcps/create", json={
    "name": "my-vmcp",
    "description": "My virtual MCP",
    "mcp_server_ids": [
        "filesystem-server",
        "github-server"
    ]
})

vmcp_id = response.json()["vmcp_id"]
print(f"Created vMCP: {vmcp_id}")

Calling Tools via vMCP

# Call a tool through the vMCP
response = httpx.post(
    f"http://localhost:8000/vmcp/{vmcp_id}/tools/call",
    json={
        "tool_name": "read_file",
        "arguments": {"path": "/tmp/test.txt"}
    }
)

result = response.json()
print(result)

🐳 Docker Deployment

Quick Start with Docker

The easiest way to run vMCP is using our pre-built Docker image:

# Run vMCP directly from Docker Hub
docker run -p 8000:8000 onexn/vmcp:latest

Open your browser to http://localhost:8000 - that's it!

Using Docker Compose (Recommended)

For a full setup with PostgreSQL database:

# Clone the repository
git clone https://github.com/codesque16/1xn_oss.git
cd 1xn_oss

# Start with Docker Compose
make docker-run
# or
docker-compose -f docker/docker-compose.yml up -d

Building Your Own Image

# Build from source
git clone https://github.com/codesque16/1xn_oss.git
cd 1xn_oss
make docker-build

# Run your custom build
docker run -p 8000:8000 your-image-name:latest

Available Tags

• onexn/vmcp:latest - Latest stable release
• onexn/vmcp:v0.1.3 - Specific version
• View all tags at: https://hub.docker.com/r/onexn/vmcp

📚 Documentation

Full documentation is available at docs.vmcp.dev (coming soon).

Key Concepts

• MCP Servers: Individual servers implementing the Model Context Protocol
• vMCPs: Virtual endpoints that aggregate multiple MCP servers
• Tools: Functions exposed by MCP servers
• Resources: Data sources accessible through MCP servers
• Prompts: Templated prompts provided by MCP servers

🤝 Contributing

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

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=vmcp --cov-report=html

# Run specific test file
pytest tests/test_mcps/test_client.py

📄 License

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

🙏 Acknowledgments

📞 Support

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

---

Made with ❤️ by the 1xn Team