MetaMCP

MetaMCP

MetaMCP は、MCP サーバーのロングテール向けの、安全でオンデマンドなゲートウェイです。MCP クライアントに、安定した 3 つのツールを提供します。

• mcp_discover は、設定済みのサーバー、キャッシュされたツールスキーマ、レビュー済みのメソッドを、すべての子サーバーを起動することなく検索します。
• mcp_call は、明示的に指定された 1 つの子ツールを遅延呼び出しします。
• mcp_run は、範囲が限定され、スキーマ検証済みの宣言的なメソッドを実行します。

MetaMCP は、すべての MCP への直接接続に取って代わるものではありません。重要度が高く、頻繁に使用され、コンパクトであるか、強力な認証が必要な MCP は直接接続のままにしてください。不規則なロングテールのサーバーは MetaMCP の背後に配置し、繰り返し行う複数ステップの作業はメソッドに昇格させます。

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

どの経路を使うか

経路	最適な用途	理由
直接 MCP	使用頻度が高く、コンパクトで、セキュリティ上重要、または基盤となるサーバー	型付きスキーマ、ネイティブ認証、明示的な承認を維持します
mcp_discover + mcp_call	ロングテールまたは不規則な機能	組み立て言語を隠さずに、クライアント側の機能を小さく保ちます
mcp_run	繰り返し行う取得 → 正規化 → 分析のワークフロー	範囲を限定した動作をテスト可能かつバージョン管理可能にし、証跡を生成します

ツール数を減らすためだけに、請求処理、インフラの変更、ID 管理、その他影響の大きいサーバーを MetaMCP 経由にしないでください。適切な境界は、思想的なものではなく、運用上のものです。

クイックスタート

Node.js 20 以降が必要です。

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

クライアントを設定する前に、モデルに公開されるサーフェス全体を確認してください。

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

インスペクターは、MCP の tools/list が返すものと同じ定義を読み取った後、設定の読み込み、ストレージのオープン、子サーバーの起動、トランスポートのバインドを行う前に終了します。--json は、自動レビューやバージョン間の差分確認に使える完全な入力スキーマを含みます。

.mcp.json を作成します。

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

子サーバーは、明示的に更新、呼び出し、またはメソッドで使用された場合にのみ起動します。通常の検出では設定とキャッシュされたスキーマを読み取りますが、すべての子サーバーを起動することはありません。

サーバー名は安定したキャッシュ ID であり、1～128 文字の英字、数字、ピリオド、アンダースコア、ハイフンのみを使用できます。パス区切り文字や、パストラバーサルを連想させる名前は拒否されます。

安全なクライアント設定

init は、--yes が指定されない限りプレビューのみです。クライアント名を指定しない場合、既存のクライアント設定ファイルのみが対象になります。

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

不正な JSON は拒否され、そのまま変更されません。名前付きクライアントは明示的に作成できます。MetaMCP がサポート対象のクライアント設定をすべて既定で作成することはありません。

クライアントを手動で設定する場合は、ゲートウェイがクライアントの作業ディレクトリに依存しないよう、絶対パスを使用してください。

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

評価には @latest が便利です。管理された環境では、アップグレードを意図的に行い、レビューできるよう、@mentu/[email protected] にバージョンを固定してください。

3 つのツール

Discover

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

検出では、実行中またはキャッシュ済みのスキーマのみを検索します。ライブのツール一覧から 1 つのサーバーを更新するには、次のようにします。

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

サーバーを指定せずに refresh を実行すると拒否されるため、エージェントが誤って設定全体に対して一斉に処理を行うことはありません。

Call

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

MetaMCP は、タイムアウトやトランスポート障害の後に子サーバーへの呼び出しを自動的に再実行することはありません。応答が失われる前に、子サーバー側で変更処理が完了している可能性があるためです。後続のメソッドで再試行できるのは、マニフェストがそのステップに idempotency: "safe" を明示的に宣言している場合のみです。

Method の実行

JSON マニフェストを .metamcp/methods/ に配置するか、--methods <directory> を渡してください。以下の子サーバー名とツール名は例示です。ご自身の設定で、レビュー済みのサーバーにバインドしてください。

{
  "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}"
  }
}

次に、以下を呼び出します。

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

Method は任意の JavaScript ではなく、宣言型です。ステップ数、期限、出力サイズに上限があり、入出力 JSON Schema、明示的な読み取り／書き込み効果、安全な補間、型付きギャップ、ステップごとのトレースを備えています。書き込みまたは混合効果の Method は、ゲートウェイの運用者が MetaMCP を --allow-writes 付きで起動しない限り無効です。

Method Mode、マニフェストスキーマ、Method の例を参照してください。この設計は、Crawlio Method Modeで説明されている一貫性レイヤーを一般化したものです。

設定とシークレット

env と HTTP の headers にある ${NAME} 参照は、既定でホスト環境から解決されます。参照を解決できない場合、起動は失敗し、子プロセスにリテラルのプレースホルダーとして渡されることはありません。

MetaMCP は、暗黙の環境変数を stdio 子プロセスにコピーしません。継承するのは、少数のランタイム許可リスト（PATH、ホーム／一時ディレクトリ／ロケール関連の変数とプラットフォーム固有の同等変数）、inheritEnv で指定した変数、および子の env ブロックで明示的に設定した値のみです。組み込み側では、キーチェーンやボールト用のカスタム SecretProvider を登録できます。

既定では、ローカルのキーワード検索で検出します。Voyage を利用したセマンティック検索を有効にするには、METAMCP_VOYAGE_API_KEY を明示的に設定してください。その場合、検出クエリは Voyage に送信され、オプションのローカル SQLite ベクトルインデックスが有効になります。暗黙の ANTHROPIC_API_KEY または VOYAGE_API_KEY 環境変数によって、ネットワーク呼び出しが有効になることはありません。

リモートの子サーバーでは、url、transportType、headers、既存の OAuth フィールドを使用します。

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

HTTP ゲートウェイ

HTTP モードは、既定で 127.0.0.1 にバインドします。

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

認証なしでループバック以外にバインドすると、安全のため起動に失敗します。リスナーを公開する前に、OAuth リソースサーバーの検証を設定するか、METAMCP_HTTP_BEARER_TOKEN を設定してください。Origin ヘッダーを含むブラウザーリクエストは、--allow-origin または METAMCP_ALLOWED_ORIGINS にオリジンを完全一致で指定しない限り拒否されます。

MetaMCP は、従来の MCP クライアントと、2026-07-28 のステートレスリクエストエンベロープを、stdio および Streamable HTTP 経由で提供します。サポート対象の境界とデプロイのガイダンスについては、アーキテクチャを参照してください。

証跡

完了した mcp_call と mcp_run の試行は、.metamcp/ledger.jsonl にシリアライズされます。ハッシュチェーン付きのポータブルなバンドルをエクスポートするには、以下を実行します。

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

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

運用台帳はリモートの証明システムではありません。エクスポートによってバンドル内の後続の変更を検出できますが、侵害されたホストがすべてのイベントを記録したことを証明するものではありません。

オプションのギャラリー

このパッケージには、引き続き人が操作するサーバーギャラリーが含まれています。

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

ランタイムが MCP ツール呼び出しに応じてパッケージをインストールすることはありません。インストールは引き続き、CLI またはユーザーが明示的に実行する操作です。

ギャラリーのエントリーは、ローカルランチャー（command + args）か、ホストされた Streamable HTTP エンドポイント（--list では 🌐 と表示）のいずれかです。ホストされたエントリーはネイティブのリモートサーバーとして .mcp.json に書き込まれます。ギャラリーがリモートサーバーを stdio ブリッジパッケージ経由でルーティングすることはありません。

0.x からのアップグレード

バージョン 1.0 では、モデル向けのプロビジョニング、スキルのアドバイス、JavaScript 実行ツールを意図的に削除しました。また、HTTP のバインド、子プロセスの環境変数の継承、再試行、init も変更されています。アップグレードする前に、1.0 への移行をお読みください。

セキュリティ

子 MCP サーバーは、それぞれ独自の権限を持つ、信頼されたローカルまたはリモートのコードです。MetaMCP はポリシーとライフサイクルの境界であり、信頼できないパッケージ向けの OS サンドボックスではありません。コマンドを確認し、適切にパッケージを固定し、認証情報のスコープを子サーバーごとに設定し、危険な直接接続型サーバーはクライアント側で人間の承認を必須にしてください。

脆弱性は、SECURITY.md に記載されている方法で非公開に報告してください。

開発

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

npm publish は完全な verify:release ゲートを再度実行します。このゲートは、ビルド済み CLI から公開ツールの構成を導き出し、パッケージ、ロックファイル、変更履歴、公式 MCP レジストリのメタデータについて、バージョンの不一致がないか確認します。

Apache-2.0 ライセンスです。Mentu AI がメンテナンスしています。