Skip to main content

Getting Started with vMCP

vMCP (Virtual MCP) aggregates multiple Model Context Protocol (MCP) servers into a unified interface, allowing AI agents to seamlessly access tools, resources, and prompts from multiple sources.

Quick Start​

Get started with vMCP in seconds using a single command:

uvx vmcp run

This command will:

  • Install all dependencies
  • Start the PostgreSQL database
  • Launch the FastAPI backend
  • Serve the frontend interface
  • Open your browser to http://localhost:8000

What is vMCP?​

vMCP acts as a virtual aggregator that:

  • Unifies Multiple MCP Servers: Connect to many MCP servers (filesystem, GitHub, databases, APIs, etc.)
  • Single Interface: AI agents see one unified vMCP instead of managing multiple connections
  • Variable Substitution: Use @param, @config, @tool(), @resource(), and @prompt() for dynamic content
  • No Authentication Required: OSS version uses a dummy user system (always user_id=1)
  • Production-Ready: Built with FastAPI, PostgreSQL, and React

Architecture​

AI Agent → vMCP → [MCP Server 1, MCP Server 2, MCP Server 3, ...]

Instead of connecting to multiple MCP servers individually, your AI agent connects to one vMCP which handles routing and aggregation.

Core Concepts​

MCP Servers​

Individual MCP protocol servers that provide specific capabilities:

  • File System MCP: Access files and directories
  • GitHub MCP: Repository and issue management
  • PostgreSQL MCP: Database queries
  • Custom MCPs: Build your own with FastMCP

vMCPs​

Virtual MCPs aggregate multiple MCP servers into one unified interface. You can create multiple vMCPs for different use cases:

  • Development vMCP: File system + Git + Documentation
  • Data Analysis vMCP: PostgreSQL + CSV + API servers
  • Content vMCP: CMS + Image processing + Search

Variable Substitution​

vMCP supports dynamic variable substitution in tool arguments:

  • @param:variable_name - Runtime parameters
  • @config:setting_name - Configuration values
  • @tool(server_name.tool_name) - Call other tools
  • @resource(server_name.resource_uri) - Reference resources
  • @prompt(server_name.prompt_name) - Use prompt templates

View Documentation Locally​

You can also start the documentation server locally:

uvx vmcp docs start

Or if you have vMCP installed:

vmcp docs start

This will start the documentation at http://localhost:3000 with live reload.

Next Steps​