Skip to main content
Glama
MetaMCP

MetaMCP

Official
by dataware-co

MetaMCP

npm version Node.js License CI

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

Path

Best fit

Why

Direct MCP

High-frequency, compact, security-sensitive, or foundational servers

Preserves typed schemas, native auth, and explicit approvals

mcp_discover + mcp_call

Long-tail or irregular capabilities

Keeps the client surface small without hiding the assembly language

mcp_run

Repeated Acquire → Normalize → Analyze workflows

Makes bounded behavior testable, versioned, and evidence-producing

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.

Related MCP server: Agent Aggregator

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.

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

Version 1.0 intentionally removes the model-facing provisioning, skill-advice, and JavaScript execution tools. It also changes HTTP binding, child environment inheritance, retries, and init. Read Migration to 1.0 before upgrading.

Security

Child MCP servers are trusted local or remote code with their own permissions. MetaMCP is a policy and lifecycle boundary, not an OS sandbox for untrusted packages. Review commands, pin packages where appropriate, scope credentials per child, and keep dangerous direct servers behind client-side human approval.

Report vulnerabilities privately as described in SECURITY.md.

Development

npm ci
npm run typecheck
npm test
./scripts/smoke-test.sh
npm run check:release
npm pack --dry-run

npm publish runs the full verify:release gate again. The gate derives the public tool surface from the built CLI and checks package, lockfile, changelog, and official MCP Registry metadata for version drift.

Apache-2.0 licensed. Maintained by Mentu AI.

Available Tools

6 tools
mcp_callB

Forward a tool call to a specific child MCP server. Retries once on crash.

Inputs: tool (required), server (required), args.

mcp_discoverA

Search tool catalogs across all child MCP servers + list server status. If no query, returns server list with status and tool counts.

Inputs: query, server.

mcp_executeA

Code-mode execution in V8 sandbox. Access provisioned servers via servers.<name>.call(tool, args). Supports async/await, sleep(ms), console.log.

Inputs: code (required).

mcp_provisionB

Intent-based provisioning. Describe what you need, MetaMCP resolves and provisions the right server.

Inputs: intent (required), context, autoProvision.

mcp_skill_adviseA

Pre-flight readiness check for a skill. Returns MCP server availability and recommendations.

Inputs: skill (required).

mcp_skill_discoverA

Search Claude Code skills with MCP readiness status. Returns skills matching query with their required MCP servers and availability.

Inputs: query (required), domain.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: discovery of servers/tools, provisioning, forwarding tool calls, code execution, skill discovery, and skill readiness checking. No two tools have overlapping functionality.

    Naming Consistency5/5

    All tools follow the 'mcp_<verb>' pattern, with skill-specific tools adding 'skill_' for clarity. The naming is consistent and predictable.

    Tool Count5/5

    With 6 tools, the set is well-scoped for a meta-server. It covers the essential operations without being excessive or insufficient.

    Completeness4/5

    The tool surface covers discovery, provisioning, calling, execution, and skill support. Minor gaps exist (e.g., no explicit unprovisioning or server management), but core agent workflows are well-supported.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Aggregates multiple MCP servers into a single endpoint, enabling LLM clients to access tools, resources, and prompts from various backends through one connection.
      19 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Aggregates multiple MCP servers and custom Python tools behind a single endpoint, with intelligent context and tool discovery for AI agents.
      -