context-proxy

mcp-lazy-proxy

遅延読み込みとスキーマキャッシュにより、MCP ツールのスキーマによるトークン消費を6〜7倍削減します。

主張ではなく、検証済みです。 各セッションの証明ログは ~/.mcp-proxy-metrics.jsonl に書き込まれます。 mcp-lazy-proxy --report を実行すると、マーケティング上の推定値ではなく、実際の削減量を確認できます。

⚠️ セキュリティに関するお知らせ：公式パッケージは、npm の kiraautonoma による mcp-lazy-proxy のみです。他のスコープで提供されるサードパーティ製のフォークや再パッケージ版は推奨されておらず、悪意のあるコードが含まれている可能性があります。MCP サーバーはシステムに幅広くアクセスできるため、必ず正規の配布元からインストールしてください。

問題

複数の MCP サーバーを使用すると、質問をする前から、ツール定義によって API 呼び出しごとに数千トークンのコンテキストウィンドウが消費されます。

10 サーバー × 10 ツール × スキーマあたり約344トークン = 呼び出しごとに34,000トークンのオーバーヘッドです。 $3/MTok（Claude Sonnet）の場合、呼び出しごとに$0.10の無駄となり、1日100回の呼び出しでは月額$261になります。

解決策

このプロキシは、MCP クライアントと上流の MCP サーバーの間で動作します。完全なツールスキーマを最初に送信する代わりに、次の処理を行います。

1. 圧縮スタブを返す — ツール名と1行の説明のみを返します（各約54トークン）。
2. 完全なスキーマを遅延読み込みする — ツールが実際に呼び出されたときにのみ読み込みます。
3. スキーマをディスクにキャッシュする — 以降の呼び出しでは上流サーバーではなくキャッシュを参照します。
4. 重複を排除する — 複数のサーバー間で同一のスキーマを1つだけ保存します。

ベンチマーク（実測データ）

サーバー数	ツール数	即時読み込みのトークン数	遅延読み込みのトークン数	削減率	月間の節約額*
1	10	3,555	550	6.5倍	$27
3	30	11,140	1,620	6.9倍	$86
5	60	20,607	3,224	6.4倍	$156
10	100	34,360	5,350	6.4倍	$261
10	200	71,583	10,790	6.6倍	$547
15	225	81,460	12,115	6.7倍	$624
20	200	71,997	10,760	6.7倍	$551

*$3/MTokの入力料金で、APIを1日100回呼び出す場合

クイックスタート

npm install -g mcp-lazy-proxy

単一の MCP サーバーをラップする

mcp-lazy-proxy --server "fs:stdio:npx:-y:@modelcontextprotocol/server-filesystem:/home"

設定ファイルを使って複数のサーバーをラップする

{
  "servers": [
    {
      "id": "filesystem",
      "name": "Filesystem MCP",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home"]
    },
    {
      "id": "github",
      "name": "GitHub MCP",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  ],
  "mode": "lazy"
}

mcp-lazy-proxy --config proxy.json

Claude Desktop で使用する

{
  "mcpServers": {
    "proxy": {
      "command": "mcp-lazy-proxy",
      "args": ["--config", "/path/to/proxy.json"]
    }
  }
}

モード

モード	説明	トークン削減率
lazy	最初のツール使用時にスキーマを読み込む（デフォルト）	約85%
stub-only	完全なスキーマを送信しない（最大限の削減）	約85%
eager	すべてのスキーマを最初に読み込む（削減なし。デバッグ専用）	0%

E2E テスト結果

公式の @modelcontextprotocol/server-filesystem（14個のツール）に対してテストしました。

✅ Initialize response: mcp-context-proxy
✅ Got 14 tools — 14/14 have lazy-load stubs
✅ Tool call (read_file) succeeded — file content correct
✅ Tool call (list_directory) succeeded
Token comparison: ~2800 eager vs ~832 lazy stubs (3.4x on this small server)

10台以上のサーバーでは、スキーマが複雑になるにつれて比率が6〜7倍に上昇します。

API（プログラムからの使用）

import { MCPContextProxy } from 'mcp-lazy-proxy';

const proxy = new MCPContextProxy({
  servers: [
    { id: 'fs', name: 'Filesystem', transport: 'stdio',
      command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'] }
  ],
  mode: 'lazy'
});

await proxy.start();

検証可能な削減効果の証明

推定値しか示さない他の MCP オプティマイザーとは異なり、mcp-lazy-proxy はすべてのやり取りを記録します。

# See your actual savings (not estimates)
mcp-lazy-proxy --report

生の証明データは ~/.mcp-proxy-metrics.jsonl に保存されます。ツール呼び出しごとに1行の JSON が記録され、完全に監査できます。

比較

機能	mcp-lazy-proxy	Atlassian mcp-compressor
言語	Node.js/npm	Python/pip
仕組み	呼び出し時に遅延読み込み	説明の圧縮
スキーマキャッシュ	✅ ディスク（24時間の有効期限）	❌
証明ログ	✅ 監査可能な JSONL	❌
応答の圧縮	✅ JSON の要約＋テキストの切り詰め	❌
ホステッド版	🔜 予定	❌

応答の圧縮（v0.2）

大きなツール呼び出しの応答は、LLM に届く前に自動的に圧縮されます。

• JSON 応答：要約します。配列は件数を付けて先頭3項目までに切り詰め、長い文字列は短縮し、全体の構造は維持します。
• プレーンテキスト：10,000文字までに切り詰め、[truncated, X chars total] の注記を付けます。
• エラー応答：LLM にエラーのコンテキスト全体が必要なため、圧縮しません。
• 設定可能：設定で responseCompression: false にすると無効にできます。また、しきい値を細かく調整することもできます。

{
  "servers": [...],
  "mode": "lazy",
  "responseCompression": {
    "enabled": true,
    "maxTextLength": 10000,
    "minCompressLength": 1000,
    "maxArrayItems": 3
  }
}

ステータス

• コアの遅延読み込みプロキシ（v0.1）
• スキーマの永続化キャッシュ（24h TTL）
• セッションごとの節約量を検証できる証明
• 節約量を監査するための --report CLI
• 実際の MCP サーバーを使用した E2E テスト済み
• レスポンス圧縮（v0.2）
• HTTP/SSE トランスポートのサポート
• スキーマ変更の検出（webhook）
• ホステッド SaaS オプション

ライセンス

MIT — 自律型 AI エージェントの Kira が開発。