AI SDK + MCP：本番エージェントシステムのための実践的統合ガイド

2026年4月7日Lin Ivan

重要ポイント

AI SDK + MCP は単なる「接続して呼ぶ」話ではありません。難しいのは capability scope、transport、retry、auth、observability です。
最も安全な出発点は、狭い discovery、明示的な tool allowlist、そしてリクエストごとの明確な runtime budget です。
MCP は discovery と invocation の境界をきれいにしますが、どの workflow にどの tool を見せるかは依然としてアプリ側の責任です。
本番のエージェントシステムでは timeout、fallback、logging の設計を最初から入れておく必要があります。
puppyone は、同じ workflow で governed context と MCP tool の両方を扱いたいときに特に相性がよくなります。

なぜデモでは簡単に見え、本番では難しくなるのか

デモの流れはいつも同じです。

AI SDK を MCP サーバーにつなぐ
いくつかの tool を公開する
モデルに tool を呼ばせる

これは良い試作です。しかし本番の統合ではありません。

本番で増えるのはコード量よりも、運用上の意思決定です。

このエージェントにどの tool を見せるのか
この環境ではどの transport を許容するのか
認証と credential rotation をどうするか
MCP サーバーが遅いときにどうするか
tool call 失敗時の fallback をどうするか
どの呼び出しに human approval が必要か
問題発生後に実行内容をどう説明するか

最小でも必要なアーキテクチャ

user request
  -> アプリ内の agent runtime
  -> workflow ごとの tool policy
  -> MCP client
  -> 1つ以上の MCP server
  -> 外部システムまたは governed context
  -> 結果の組み立て
  -> logs / approvals / traces

多くのチームが飛ばしがちなのが tool policy です。

discovery は protocol の機能であり、exposure は product の判断です。

本当に重要な5つの判断

1. Discovery は permission ではない

SDK が20個の tool を列挙できたとしても、その workflow が20個すべてを見るべきだとは限りません。

Discovery は上限集合、runtime allowlist は実際の実行境界として扱うべきです。

2. Transport は信頼性の判断

現行の AI SDK ドキュメントでは、本番には HTTP transport、ローカルには stdio が勧められています。これは単なる実装差ではなく、firewall、retry、proxy、運用責任の持ち方に影響します。

正しいルールはシンプルです。

環境が安定運用できる最も単純な transport を使う
retry を明確に制限する
timeout の挙動を明示する

3. Tool description はモデル行動を左右する

説明が曖昧だと、tool の使い方も曖昧になります。似た tool が複数あると、モデルは解決ではなく選択に token を使ってしまいます。

慎重なオペレーターのように tool を説明してください。

何をするか
何をしないか
いつ使うか
どんな入力が必要か
どう失敗するか

4. すべての tool call に budget が必要

モデルを自由にしてはいけないことがあります。

2つで足りるのに10個呼ぶ
無限に retry する
巨大 payload を prompt に流し込む
read-only と write tool を無造作に混ぜる

5. Log は機能の一部

「モデルの判断が悪かった」だけでは足りません。最低でも必要なのは以下です。

request ID
公開された tool 一覧
実際に選ばれた tool
送信引数
latency と failure
必要なら approval 状態

失敗を減らすための1つの表

選択	チームが好む理由	どこで壊れるか
発見した tool を全部読み込む	試作が速い	本番では広すぎて危険
schema と tool set を明示する	型安全性と制御が高い	維持の手間が増える

実務上のルールはこうです。