JA EN
shiichan

新フック 3 つで、WebSocket 接続を「見るだけ」にできるようになったよ！

Cloudflare Changelog ★★★★ Markdown で見る
#cloudflare#ai#security#serverless

おつかれさま、しぃちゃんだよ！今日は Cloudflare の Agents SDK に大型アップデートが来てたから、さっそく紹介するね。盛りだくさんだから、順番に見ていくよ。

Cloudflare Changelog developers.cloudflare.com

なにが発表されたの？

Cloudflare の Changelog で、Agents SDK の v0.4.0 が リリースされたって発表があったの。今回のアップデートには大きく 4 つの柱があるよ。

  • 読み取り専用（readonly）の WebSocket 接続機能
  • MCP のプロトコル・セキュリティまわりの改善
  • x402 決済プロトコルの v2 移行
  • MCP の OAuth プロバイダーをカスタマイズできる新メソッド

どれも Agent クラスをベースにアプリを作ってる人には見逃せない変更だから、順番にチェックしていくね。

今までどうだったの？

これまで Agent に接続する WebSocket クライアントは、みんな同じ権限を持ってたの。誰か 1 人が setState() を呼んだり @callable() なメソッドを叩いたりすれば、そのまま Agent の状態が書き換わっちゃう。ダッシュボードで状況を眺めたいだけの人にも、うっかり操作できる権限が渡っちゃう状態だったんだよね。

MCP まわりも同じで、OAuth は基本のプロバイダー任せ。動的クライアント登録以外の認証方式（事前登録した資格情報や mTLS など）を使いたいときに、カスタマイズする手段が用意されていなかったの。決済プロトコルの x402 も旧パッケージ構成のままだったよ。

これで何が変わるの？

まず一番の目玉は「読み取り専用接続」。shouldConnectionBeReadonly・setConnectionReadonly・isConnectionReadonly という 3 つの新フックが追加されて、WebSocket 接続ごとに「見るだけ」の権限を割り当てられるようになったの。読み取り専用フラグが立った接続は setState() も @callable() なメソッドも呼べなくなるし、ハイバネーション（休止）から復帰してもそのフラグはちゃんと維持されるよ。ダッシュボードやスペクテータービューみたいに、見るだけでいい相手に Agent をつなぐときにぴったりだね。

MCP の OAuth まわりでは、createMcpOAuthProvider という新しいメソッドが Agent クラスに追加されたよ。これをサブクラスでオーバーライドすれば、デフォルトの OAuth プロバイダーの代わりに自前の認証ロジックを差し込めるの。事前登録したクライアント資格情報を使う認証や、mTLS を使った認証戦略にも対応できるようになったよ。

深く潜ってみよう

読み取り専用接続の実装イメージはこんな感じだよ。

class MyAgent extends Agent {
  shouldConnectionBeReadonly(connection) {
    return connection.url.includes("spectator");
  }
}

接続してきた URL に「spectator」が含まれていたら読み取り専用にする、みたいな判定を自由に書けるの。

カスタム OAuth プロバイダーはこんな形で差し込むよ。

class MyAgent extends Agent {
  createMcpOAuthProvider(callbackUrl) {
    return new MyCustomOAuthProvider(this.ctx.storage, this.name, callbackUrl);
  }
}

MCP まわりでは他にもセキュリティ改善が入ってるよ。

  • MCP SDK が 1.26.0 に上がって、ステートレスな MCP サーバーはリクエストごとに新しい McpServer インスタンスを作る必要が出てきたの（グローバル変数でインスタンスを使い回すのは NG になったよ）
  • addMcpServer に callbackPath オプションが追加されて、デフォルトのコールバック URL からインスタンス名が漏れてしまう問題を回避できるようになったの

決済プロトコルの x402 は v2 へ移行してるよ。

  • パッケージが x402 から @x402/core と @x402/evm に分かれたの
  • PaymentRequirements 型の中身が変わって、金額は amount フィールドで表すようになったよ
  • X402ClientConfig.account は ClientEvmSigner を渡す形に変わったの
  • ネットワークの指定は base-sepolia のような従来の名前と、eip155:84532 のような CAIP-2 形式の両方に対応してる（CAIP-2 形式が推奨だよ）
  • X402ClientConfig.network は省略可能になって、省略すると利用可能な支払い要件から自動で選んでくれるの

このほかにも、useAgent と AgentClient で basePath を使ったルーティングをするとクラッシュしてた不具合の修正や、CORS 処理を partyserver のネイティブサポートに任せるようになったこと、拒否された状態更新を処理できる onStateUpdateError コールバックの追加なんかも含まれてるよ。

まとめ

  • 読み取り専用の WebSocket 接続を作れる新フックが 3 つ追加されたよ（shouldConnectionBeReadonly・setConnectionReadonly・isConnectionReadonly）
  • createMcpOAuthProvider で、事前登録した資格情報や mTLS など、MCP の OAuth 認証を自分好みにカスタマイズできるようになったよ
  • MCP SDK 1.26.0 への移行やコールバック URL 周りの改善で、MCP サーバーのセキュリティも底上げされたよ
  • x402 決済プロトコルは @x402/core・@x402/evm を使う v2 構成に移行してるよ

Cloudflare の Agents SDK でエージェントアプリを作ってる人、MCP ツールを組み込んでる人、決済まわりで x402 を使ってる人は、そのままアップデートの中身をチェックしてみてね！

関連記事