shield

@bolyra/shield

Stdio MCP 認証プロキシです。MCP サーバーをラップし、ツールごとの権限適用、リプレイ攻撃防止、監査レシートを実現します。サーバーのコード変更は不要です。

クイックスタート

npx @bolyra/shield --server "npx @modelcontextprotocol/server-filesystem /tmp" --dev

Shield は対象のサーバーを子プロセスとして起動し、tools/call リクエストをインターセプトしてエージェントの認証情報を検証し、転送前にツールポリシーを適用します。

設定

shield.yaml を作成します。

devMode: true
defaultDeny: true

nonce:
  store: memory
  maxProofAge: 300

receipts:
  enabled: true
  output: stderr

tools:
  read_file:
    requireBitmask: 1    # READ_DATA
  write_file:
    requireBitmask: 2    # WRITE_DATA
  delete_file:
    requireBitmask: 2    # WRITE_DATA

次に、以下を実行します。

npx @bolyra/shield --server "node my-server.js" --config shield.yaml

デフォルト拒否

デフォルトでは、ポリシーエントリーのないツールは（認証のみがチェックされて）許可されます。defaultDeny: true を設定すると、tools: マップに記載されていないツール名への tools/call はすべて拒否されます。

学習モード

設定を手作業で書かずに、サーバー自身のツールリストから安全な初期設定を生成できます。

npx @bolyra/shield --learn --server "node my-server.js"

学習モードではサーバーを起動し、MCP ハンドシェイク（initialize → notifications/initialized → tools/list、ページネーションに従います）を実行した後、次の内容を含む shield.yaml（または --config で指定したパス）を書き込みます。

• defaultDeny: true — サーバーが後から追加するものは、許可するまで拒否されます
• 検出されたすべてのツールに requireBitmask: 1（READ_DATA）を設定 — 最小権限の基準です
• _generated 出所情報ブロック（元のコマンド＋タイムスタンプ）

既存の設定ファイルを上書きすることはありません。また、ページネーションは50ページまでに制限され、30秒後にタイムアウトします。出力は初期設定です。本番環境で使用する前に各ツールを確認し、requireBitmask を引き上げてください（例：write_file → 2）。

仕組み

Agent ←stdin/stdout→ Shield ←stdin/stdout→ MCP Server
                       │
                 verifyBundle()
                 checkToolPolicy()
                 nonceStore.markIfFresh()
                 emitReceipt()

• initialize、tools/list、ping — 認証なしで転送されます
• tools/call — params._meta.bolyra から証明情報を抽出して検証し、ポリシーを確認した後、転送または拒否されます
• レシートは stderr に出力されます（stdout は MCP トランスポートです）

権限ビットマスク

ビット	権限
0	READ_DATA
1	WRITE_DATA
2	FINANCIAL_SMALL
3	FINANCIAL_MEDIUM
4	FINANCIAL_UNLIMITED
5	SIGN_ON_BEHALF
6	SUB_DELEGATE
7	ACCESS_PII

Shield と Gateway の比較

	Shield	Gateway
トランスポート	stdio	HTTP
ユースケース	ローカル MCP サーバー（Claude Desktop、Cursor）	リモート／ネットワーク接続された MCP サーバー
ラップ方法	子プロセスを起動	リバースプロキシ
証明情報の取得元	params._meta.bolyra	Authorization: Bolyra <base64> ヘッダー
レシート	stderr	stdout／ファイル／Webhook

どちらも @bolyra/mcp の同じ verifyBundle() と checkToolPolicy() を使用します。

ライブラリの使用方法

import { createShield, loadShieldConfig } from '@bolyra/shield';

const config = loadShieldConfig('./shield.yaml');
const { child, stop } = createShield(config);

リンク

• Gateway（HTTP） — HTTP MCP サーバー向け
• MCP ミドルウェア — サーバーコードに認証を組み込む場合
• Bolyra のドキュメント