MetaMCP

One MCP server to rule them all.

MetaMCP is a proxy that lets you register a single MCP server in your AI client, while running as many child MCP servers as you want underneath it — all forwarded transparently.

Think of it like a power strip: instead of plugging 5 things into the wall separately, you plug one power strip in and everything runs through it.

Why?

MCP (Model Context Protocol) is how AI assistants connect to external tools — things like "read a file", "search GitHub", "query a database". Most AI clients let you configure multiple MCP servers, but managing them all separately gets messy fast. MetaMCP aggregates them into one connection, with automatic namespacing so there are never name collisions.

Works with any MCP-compatible client: Claude Desktop, Cursor, Windsurf, Cline, and others.

Quick start

Option A — Use directly via npx (no install needed)

npx @vladimir.kozlov/metamcp --config ./config.json

Option B — Clone and run locally

git clone https://github.com/vlkozl/metamcp
cd metamcp
npm install
npm run build
npm start

Configuration

Copy the example config and fill in your servers:

cp config.example.json config.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

The format is the standard mcpServers block used by most MCP clients — you can copy-paste your existing config straight in.

The config path can be overridden:

• Flag: --config /path/to/file.json
• Env var: METAMCP_CONFIG=/path/to/file.json

config.json is gitignored — it's safe to store tokens there.

Wiring into your AI client

Register MetaMCP as a single MCP server in your AI client of choice. The exact config location varies by client — consult its docs — but the entry looks like this:

{
  "mcpServers": {
    "metamcp": {
      "command": "npx",
      "args": [
        "@vladimir.kozlov/metamcp",
        "--config", "/path/to/your/config.json"
      ]
    }
  }
}

Common config locations:

| Client | Config file | |---|---| | Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json | | Claude Desktop (Mac) | ~/Library/Application Support/Claude/claude_desktop_config.json | | Cursor | .cursor/mcp.json in your project, or ~/.cursor/mcp.json globally | | Windsurf | ~/.codeium/windsurf/mcp_config.json | | Cline | VS Code settings → Cline → MCP Servers |

After saving, restart your client. All your child servers' tools will appear, prefixed with their server name (e.g. filesystem__read_file, github__search_repositories).

How it works

Every tool, resource, and prompt from every child server is collected at startup and exposed through a single MCP interface. To avoid name collisions, everything is namespaced:

filesystem → read_file    becomes    filesystem__read_file
github     → read_file    becomes    github__read_file

When your AI client calls filesystem__read_file, MetaMCP strips the prefix and forwards read_file to the correct child. The response comes back unchanged.

If a child server crashes mid-session, its tools are automatically removed and the client is notified to refresh — the proxy keeps running with the remaining servers.

AI client
     │  CallTool: filesystem__read_file
     ▼
  MetaMCP (this project)
     │  resolves → filesystem child, original name: read_file
     ▼
  filesystem server process
     │  returns file contents
     ▼
  MetaMCP forwards response
     │
     ▼
AI client receives result

Using in Windows Sandbox

Sandbox resets on every launch. Use a .wsb file to map your config folder in automatically:

<Configuration>
  <MappedFolders>
    <MappedFolder>
      <HostFolder>C:\Users\you\metamcp-config</HostFolder>
      <SandboxFolder>C:\metamcp-config</SandboxFolder>
      <ReadOnly>true</ReadOnly>
    </MappedFolder>
  </MappedFolders>
</Configuration>

Then inside Sandbox:

winget install OpenJS.NodeJS.LTS
# restart shell, then:
npx @vladimir.kozlov/metamcp --config C:\metamcp-config\config.json

Requirements

• Node.js 18+

License

MIT