{
  "markdown": "# MetaMCP\n\n[![npm version](https://img.shields.io/npm/v/@mentu/metamcp)](https://www.npmjs.com/package/@mentu/metamcp)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)\n[![CI](https://github.com/mentu-ai/metamcp/actions/workflows/ci.yml/badge.svg)](https://github.com/mentu-ai/metamcp/actions/workflows/ci.yml)\n\nMetaMCP is a secure, on-demand gateway for the long tail of MCP servers. It gives an MCP client three stable tools:\n\n- `mcp_discover` finds configured servers, cached tool schemas, and reviewed Methods without starting every child.\n- `mcp_call` lazily calls one explicitly named child tool.\n- `mcp_run` executes a bounded, schema-validated declarative Method.\n\nMetaMCP 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.\n\n```text\n                               ┌─ direct: GitHub / Codex Apps / core runtime\nMCP client ────────────────────┤\n                               └─ MetaMCP (3 tools)\n                                    ├─ discover cached capabilities\n                                    ├─ call one lazy child\n                                    └─ run reviewed Methods\n```\n\n## When to use which path\n\n| Path | Best fit | Why |\n|---|---|---|\n| Direct MCP | High-frequency, compact, security-sensitive, or foundational servers | Preserves typed schemas, native auth, and explicit approvals |\n| `mcp_discover` + `mcp_call` | Long-tail or irregular capabilities | Keeps the client surface small without hiding the assembly language |\n| `mcp_run` | Repeated Acquire → Normalize → Analyze workflows | Makes bounded behavior testable, versioned, and evidence-producing |\n\nDo 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.\n\n## Quick start\n\nRequires Node.js 20 or newer.\n\n```bash\nnpx @mentu/metamcp@latest --config .mcp.json\n```\n\nInspect the complete model-facing surface before configuring a client:\n\n```bash\nnpx @mentu/metamcp@latest tools\nnpx @mentu/metamcp@latest tools --json\n```\n\nThe 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.\n\nCreate `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem@2026.7.10\", \"/path/to/allowed/files\"]\n    },\n    \"internal-api\": {\n      \"command\": \"node\",\n      \"args\": [\"./servers/internal-api.js\"],\n      \"env\": { \"API_TOKEN\": \"${INTERNAL_API_TOKEN}\" },\n      \"inheritEnv\": [\"HTTP_PROXY\"]\n    }\n  }\n}\n```\n\nChild 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.\n\nServer names are stable cache identities and must contain 1-128 letters, numbers, dots, underscores, or hyphens; path separators and traversal-like names are rejected.\n\n### Safe client setup\n\n`init` is preview-only unless `--yes` is supplied. Without a named client it considers existing client config files only.\n\n```bash\nmetamcp init                         # preview, no writes\nmetamcp init --client Codex          # preview one client\nmetamcp init --client Codex --yes    # apply atomically and write a .bak\n```\n\nMalformed JSON is rejected and left untouched. A named client may be created explicitly; MetaMCP never creates every supported client config by default.\n\nFor a manual client configuration, use an absolute path so the gateway does not depend on the client's working directory:\n\n```json\n{\n  \"mcpServers\": {\n    \"metamcp\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@mentu/metamcp@latest\",\n        \"--config\",\n        \"/absolute/path/to/.mcp.json\"\n      ]\n    }\n  }\n}\n```\n\n`@latest` is convenient for evaluation. Pin `@mentu/metamcp@1.0.0` in controlled environments so upgrades are deliberate and reviewable.\n\n## The three tools\n\n### Discover\n\n```json\n{ \"query\": \"capture screenshot\", \"kind\": \"tool\" }\n```\n\nDiscovery searches only live or cached schemas. To refresh one server from its live tool list:\n\n```json\n{ \"server\": \"browser\", \"refresh\": true }\n```\n\n`refresh` without a server is rejected so an agent cannot accidentally fan out across the whole configuration.\n\n### Call\n\n```json\n{\n  \"server\": \"browser\",\n  \"tool\": \"capture_page\",\n  \"args\": { \"url\": \"https://example.com\" },\n  \"timeoutMs\": 60000\n}\n```\n\nMetaMCP 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\"`.\n\n### Run a Method\n\nPut 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:\n\n```json\n{\n  \"apiVersion\": \"metamcp.io/v1alpha1\",\n  \"kind\": \"Method\",\n  \"metadata\": {\n    \"name\": \"content.acquire-and-normalize\",\n    \"version\": \"1.0.0\",\n    \"description\": \"Acquire content and normalize it into a stable record\"\n  },\n  \"spec\": {\n    \"effects\": \"read\",\n    \"inputSchema\": {\n      \"type\": \"object\",\n      \"properties\": { \"url\": { \"type\": \"string\" } },\n      \"required\": [\"url\"],\n      \"additionalProperties\": false\n    },\n    \"steps\": [\n      {\n        \"id\": \"acquire\",\n        \"server\": \"fetch\",\n        \"tool\": \"fetch\",\n        \"args\": { \"url\": \"${input.url}\" }\n      },\n      {\n        \"id\": \"normalize\",\n        \"server\": \"content\",\n        \"tool\": \"normalize\",\n        \"dependsOn\": [\"acquire\"],\n        \"args\": { \"document\": \"${steps.acquire.structuredContent}\" }\n      }\n    ],\n    \"output\": \"${steps.normalize.structuredContent}\"\n  }\n}\n```\n\nThen call:\n\n```json\n{ \"method\": \"content.acquire-and-normalize\", \"input\": { \"url\": \"https://example.com\" } }\n```\n\nMethods 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`.\n\nSee [Method Mode](docs/METHOD-MODE.md), the [manifest schema](schemas/method-v1alpha1.schema.json), and the [example Method](examples/methods/content.acquire-and-normalize.method.json). The design generalizes the consistency layer documented by [Crawlio Method Mode](https://docs.crawlio.app/mcp/method-mode?utm_source=github&utm_medium=docs&utm_campaign=mcp-setup&utm_content=metamcp-method-mode&utm_term=method-mode).\n\n## Configuration and secrets\n\n`${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.\n\nMetaMCP 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.\n\nDiscovery 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.\n\nRemote child servers use `url`, `transportType`, `headers`, and the existing OAuth fields:\n\n```json\n{\n  \"mcpServers\": {\n    \"remote\": {\n      \"url\": \"https://mcp.example.com/mcp\",\n      \"transportType\": \"http\",\n      \"headers\": { \"Authorization\": \"Bearer ${REMOTE_TOKEN}\" }\n    }\n  }\n}\n```\n\n## HTTP gateway\n\nHTTP mode binds to `127.0.0.1` by default:\n\n```bash\nmetamcp --transport http --port 8080 --config .mcp.json\n```\n\nAn 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`.\n\nMetaMCP serves legacy MCP clients and the 2026-07-28 stateless request envelope over stdio and Streamable HTTP. See [Architecture](docs/ARCHITECTURE.md) for the supported boundary and deployment guidance.\n\n## Evidence\n\nCompleted `mcp_call` and `mcp_run` attempts are serialized into `.metamcp/ledger.jsonl`. Export a portable hash-linked bundle:\n\n```bash\nmetamcp export-evidence \\\n  --ledger .metamcp/ledger.jsonl \\\n  --out .metamcp/evidence-bundle.json\n\nmetamcp export-evidence --out .metamcp/evidence-bundle.json --verify\n```\n\nThe 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.\n\n## Optional gallery\n\nThe package still ships a human-operated server gallery:\n\n```bash\nmetamcp add --list\nmetamcp add playwright sentry --config .mcp.json\n```\n\nThe runtime never installs packages in response to an MCP tool call. Installation remains an explicit CLI/user action.\n\n## Upgrade from 0.x\n\nVersion 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](docs/MIGRATION-1.0.md) before upgrading.\n\n## Security\n\nChild 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.\n\nReport vulnerabilities privately as described in [SECURITY.md](SECURITY.md).\n\n## Development\n\n```bash\nnpm ci\nnpm run typecheck\nnpm test\n./scripts/smoke-test.sh\nnpm run check:release\nnpm pack --dry-run\n```\n\n`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.\n\nApache-2.0 licensed. Maintained by [Mentu AI](https://mentu.ai).\n",
  "bytes": 10699,
  "sha": "2439965f128f9301df449003d0a5aa8871104fda03f76c7ea00f3b4c081859c3",
  "repo_slug": "mentu-ai/metamcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mentu_ai_metamcp_e96f566e/readme"
}