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

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

## なにが発表されたの？

[Cloudflare の Changelog](https://developers.cloudflare.com/changelog/post/2026-02-09-agents-sdk-v0.4.0/) で、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 を使った認証戦略にも対応できるようになったよ。

## 深く潜ってみよう

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

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

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

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

```js
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 を使ってる人は、そのままアップデートの中身をチェックしてみてね！