MetaMCP MCP server

MetaMCP

MetaMCP is a secure, on-demand gateway for the long tail of MCP servers. It gives an MCP client three stable tools:

• mcp_discover finds configured servers, cached tool schemas, and reviewed Methods without starting every child.
• mcp_call lazily calls one explicitly named child tool.
• mcp_run executes a bounded, schema-validated declarative Method.

MetaMCP is deliberately not a replacement for every direct MCP connection. Keep important, frequently used, compact, or strongly authenticated MCPs direct. Put irregular long-tail servers behind MetaMCP, and promote repeated multi-step rituals into Methods.

┌─ direct: GitHub / Codex Apps / core runtime
MCP client ────────────────────┤
                               └─ MetaMCP (3 tools)
                                    ├─ discover cached capabilities
                                    ├─ call one lazy child
                                    └─ run reviewed Methods

When to use which path

Do not route billing, infrastructure mutation, identity, or another high-consequence server through MetaMCP merely to reduce tool count. The right boundary is operational, not ideological.

Quick start

Requires Node.js 20 or newer.

npx @mentu/metamcp@latest --config .mcp.json

Inspect the complete model-facing surface before configuring a client:

npx @mentu/metamcp@latest tools
npx @mentu/metamcp@latest tools --json

The inspector reads the same definitions returned by MCP tools/list, then exits before loading configuration, opening storage, starting a child, or binding a transport. --json includes the complete input schemas for automated review and version-to-version diffs.

Create .mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem@2026.7.10", "/path/to/allowed/files"]
    },
    "internal-api": {
      "command": "node",
      "args": ["./servers/internal-api.js"],
      "env": { "API_TOKEN": "${INTERNAL_API_TOKEN}" },
      "inheritEnv": ["HTTP_PROXY"]
    }
  }
}

Child servers start only when explicitly refreshed, called, or used by a Method. Plain discovery reads configuration and cached schemas; it does not spawn all children.

Server names are stable cache identities and must contain 1-128 letters, numbers, dots, underscores, or hyphens; path separators and traversal-like names are rejected.

Safe client setup

init is preview-only unless --yes is supplied. Without a named client it considers existing client config files only.

metamcp init                         # preview, no writes
metamcp init --client Codex          # preview one client
metamcp init --client Codex --yes    # apply atomically and write a .bak

Malformed JSON is rejected and left untouched. A named client may be created explicitly; MetaMCP never creates every supported client config by default.

For a manual client configuration, use an absolute path so the gateway does not depend on the client's working directory:

Shortened. The full README is on GitHub.