MCP 専用構成からマルチトランスポートへの移行

概要

統合を MCP の stdio トランスポートから REST または gRPC トランスポートへ移行します。エンジンの動作は変わりません。カタログ、リスクモデル、確認ゲートは同一のままです。変更点は 3 つだけです。ワイヤープロトコル、認証、並行処理モデルです。

インストール

composer require nextpdf/server
./vendor/bin/rr get-binary

概念の概要

このパッケージの初期のドキュメントでは、単一のトランスポート、つまり stdio 上の MCP について説明していました。現在、このパッケージは同じツールレジストリを 3 つのトランスポートで提供します。移行は 2 つのステップで行います。ネットワーク対応のトランスポートを選び、MCP の呼び出しをそのトランスポートにマッピングします。ドキュメントのロジックを書き換える必要はありません。

デプロイ形態に合ったトランスポートを選択します。

MCP のまま使用するのは、単一のローカルエージェント、ネットワークホップのない最小のレイテンシー、または MCP ネイティブのクライアント（たとえばローカルの IDE アシスタント）が必要な場合です。
REST へ移行するのは、クライアントごとの API キーを使ったマルチクライアントアクセス、コンテナーまたは Kubernetes でのデプロイ、クライアントごとのレート制限、非同期ジョブ、あるいは任意の言語で書かれたクライアントが必要な場合です。
gRPC へ移行するのは、型付きの契約、大きな PDF のサーバーストリーミング、相互 TLS によるサービス間デプロイが必要な場合です。

API サーフェス

変わらないもの

ツールレジストリと、ランタイムに依存するカタログ（/connect/tool-catalog/ を参照）。
4 段階のリスクモデルと確認ゲート（/connect/hitl-risk-tiers/ を参照）。
ドキュメントモデルとエンジンのセマンティクス。

変わるもの

観点	MCP（stdio）トランスポート	REST	gRPC
ワイヤーフォーマット	stdio 上の JSON-RPC 2.0	HTTP 上の JSON	gRPC 上の Protobuf
認証	なし（ローカルのサブプロセス）	`Authorization: Bearer` による API キー	呼び出しメタデータ内のベアラートークン
並行処理	1 プロセス、1 呼び出し	RoadRunner のワーカープール	RoadRunner の gRPC プール
非同期	該当なし	ジョブエンドポイント	ジョブ RPC
ストリーミング	該当なし	同期ボディ	サーバーストリーミング RPC

概念のマッピング

典型的な MCP のシーケンスは、create_pdf、コンテンツツール、output_pdf の順に実行する流れです。REST では、これは順序付けされた operations 配列を含む、1 回のステートレスな POST /api/v1/render にまとまります。ステップごとの状態が必要な場合は、代わりにオプトイン方式のセッションエンドポイントを使用します。gRPC では、これに相当するのは Render RPC、またはチャンク単位で配信する場合は RenderStream です。ステートフルなビルドには、CreateSession、SessionOperation、SessionRender の各 RPC を使用します。

MCP のツールシーケンス	REST	gRPC
`create_pdf` ＋コンテンツツール＋ `output_pdf`	`POST /api/v1/render`	`Render` / `RenderStream`
複数の呼び出しにまたがるステートフルなビルド	`POST /api/v1/sessions`（＋セッション操作）	`CreateSession`（＋ `SessionOperation`）
長時間のレンダリング	`POST /api/v1/jobs` の後に結果をポーリング	`SubmitJob` の後に `GetJobResult`
ティアでゲートされた操作	`POST /api/v1/<operation>`	`ExecuteCapability`

コードサンプル — クイックスタート

MCP の呼び出し：

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"add_text","arguments":{"text":"Hello"}}}

は、次の REST リクエストになります：

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"Hello"}]}' \
  --output hello.pdf

コードサンプル — 本番環境

段階的な移行中は、両方のトランスポートを実行します。統合された RoadRunner プロファイルは、1 つのスーパーバイザーから REST と gRPC を提供します。従来の MCP 統合は、引き続き適している箇所ではローカルで動作し続けます：

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

移行対象となる共有状態はありません。これらのトランスポートは、同じエンジン上で動作する独立したプロセスです。クライアントを段階的に切り替えます。

エッジケースと注意点

認証を追加します。 MCP トランスポートはローカルのサブプロセスであるため、認証はありませんでした。ネットワーク対応のトランスポートでは、ヘルスチェック以外のすべてのリクエストで有効な API キーが必要です。切り替え前にキーをプロビジョニングします。/connect/security-and-operations/. を参照してください。
確認ゲートは引き続き発動します。 approval_required ツールは、MCP の場合とまったく同じように REST と gRPC でも確認を求めます。確認フローを新しい統合に引き継いでください。このゲートが MCP 専用であると想定しないでください。/connect/hitl-risk-tiers/. を参照してください。
ティアによるゲートは変わりません。 Pro または Enterprise の操作には、MCP で対応するツールがそのパッケージを必要としていたのとまったく同じように、新しいトランスポート上で nextpdf/premium のインストールと、権限を付与されたキーが必要です。
冪等性は新しく、有用です。 REST では、stdio トランスポートには存在しなかった冪等性の制御が追加されます。これを使用して、ジョブの送信を安全に再試行できるようにします。/connect/production-usage/. を参照してください。

パフォーマンス

MCP は単一プロセスであり、1 つのローカルエージェントに対して最小のレイテンシーを実現します。ネットワーク対応のトランスポートでは、ワーカープールとネットワークホップが追加されます。その代わりに、多数の同時クライアントにスケールできます。ワーカーが占有されないように、長時間のレンダリングは新しいトランスポート上の非同期ジョブ経路へ移します。

セキュリティに関する注意

stdio から移行するということは、ネットワークへの露出を引き受けることを意味します。REST の前段で TLS を終端し、信頼できないネットワーク上の gRPC には相互 TLS を使用し、キーをクライアントごとにスコープし、enabled_tools は最小限に保ちます。MCP トランスポートの資格情報なしのモデルが安全なのは、それがローカルのサブプロセスである場合に限られます。その露出をネットワーク上で再現しないでください。/connect/security-and-operations/. を参照してください。

準拠

このページは移行ガイダンスです。プロトコルと認証に関する出典は、/transports/mcp/、/transports/rest/、/transports/grpc/、および /connect/security-and-operations/. に固定されています。

商用コンテキスト

ティアでゲートされた操作には、トランスポートに関係なく nextpdf/premium が必要です。移行しても、何が core で何が Premium かは変わりません。変わるのは、カタログへの到達方法だけです。