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:

{
  "mcpServers": {
    "metamcp": {
      "command": "npx",
      "args": [
        "-y",
        "@mentu/metamcp@latest",
        "--config",
        "/absolute/path/to/.mcp.json"
      ]
    }
  }
}

@latest is convenient for evaluation. Pin @mentu/metamcp@1.0.0 in controlled environments so upgrades are deliberate and reviewable.

The three tools

Discover

{ "query": "capture screenshot", "kind": "tool" }

Discovery searches only live or cached schemas. To refresh one server from its live tool list:

{ "server": "browser", "refresh": true }

refresh without a server is rejected so an agent cannot accidentally fan out across the whole configuration.

Call

{
  "server": "browser",
  "tool": "capture_page",
  "args": { "url": "https://example.com" },
  "timeoutMs": 60000
}

MetaMCP never automatically replays a child call after a timeout or transport failure. The child may have completed a mutation before the response was lost. A later Method may retry only when its manifest explicitly declares that step idempotency: "safe".

Run a Method

Put JSON manifests in .metamcp/methods/ or pass --methods <directory>. The child server and tool names below are illustrative; bind them to reviewed servers in your own config:

{
  "apiVersion": "metamcp.io/v1alpha1",
  "kind": "Method",
  "metadata": {
    "name": "content.acquire-and-normalize",
    "version": "1.0.0",
    "description": "Acquire content and normalize it into a stable record"
  },
  "spec": {
    "effects": "read",
    "inputSchema": {
      "type": "object",
      "properties": { "url": { "type": "string" } },
      "required": ["url"],
      "additionalProperties": false
    },
    "steps": [
      {
        "id": "acquire",
        "server": "fetch",
        "tool": "fetch",
        "args": { "url": "${input.url}" }
      },
      {
        "id": "normalize",
        "server": "content",
        "tool": "normalize",
        "dependsOn": ["acquire"],
        "args": { "document": "${steps.acquire.structuredContent}" }
      }
    ],
    "output": "${steps.normalize.structuredContent}"
  }
}

Then call:

{ "method": "content.acquire-and-normalize", "input": { "url": "https://example.com" } }

Methods are declarative rather than arbitrary JavaScript. They have bounded step counts, deadlines and output sizes; input/output JSON Schemas; explicit read/write effects; safe interpolation; typed gaps; and a per-step trace. Write or mixed-effect Methods are disabled unless the gateway operator starts MetaMCP with --allow-writes.

See Method Mode, the manifest schema, and the example Method. The design generalizes the consistency layer documented by Crawlio Method Mode.

Configuration and secrets

${NAME} references in env and HTTP headers resolve from the host environment by default. An unresolved reference fails startup; it is never passed to a child as a literal placeholder.

MetaMCP does not copy its ambient environment into stdio children. It inherits only a small runtime allowlist (PATH, home/temp/locale variables, and platform equivalents), variables named in inheritEnv, and values explicitly set in the child env block. Embedders can install a custom SecretProvider for a keychain or vault.

Discovery is local keyword search by default. To opt into Voyage-backed semantic search, set METAMCP_VOYAGE_API_KEY explicitly; discovery queries will then be sent to Voyage and the optional local SQLite vector index will be enabled. Ambient ANTHROPIC_API_KEY or VOYAGE_API_KEY variables never activate network calls.

Remote child servers use url, transportType, headers, and the existing OAuth fields:

{
  "mcpServers": {
    "remote": {
      "url": "https://mcp.example.com/mcp",
      "transportType": "http",
      "headers": { "Authorization": "Bearer ${REMOTE_TOKEN}" }
    }
  }
}

HTTP gateway

HTTP mode binds to 127.0.0.1 by default:

metamcp --transport http --port 8080 --config .mcp.json

An unauthenticated non-loopback bind fails closed. Configure OAuth resource-server validation or METAMCP_HTTP_BEARER_TOKEN before exposing the listener. Browser requests with an Origin header are denied unless the exact origin is supplied with --allow-origin or METAMCP_ALLOWED_ORIGINS.

MetaMCP serves legacy MCP clients and the 2026-07-28 stateless request envelope over stdio and Streamable HTTP. See Architecture for the supported boundary and deployment guidance.

Evidence

Completed mcp_call and mcp_run attempts are serialized into .metamcp/ledger.jsonl. Export a portable hash-linked bundle:

metamcp export-evidence \
  --ledger .metamcp/ledger.jsonl \
  --out .metamcp/evidence-bundle.json

metamcp export-evidence --out .metamcp/evidence-bundle.json --verify

The operational ledger is not a remote attestation system. The export detects later changes inside a bundle; it does not prove that a compromised host recorded every event.

Optional gallery

The package still ships a human-operated server gallery:

metamcp add --list
metamcp add playwright sentry --config .mcp.json

The runtime never installs packages in response to an MCP tool call. Installation remains an explicit CLI/user action.

Gallery entries are either a local launcher (command + args) or a hosted Streamable HTTP endpoint (url, shown as 🌐 in --list). Hosted entries are written to .mcp.json as native remote servers; the gallery never routes a remote server through a stdio bridge package.

Upgrade from 0.x