{"id":212,"date":"2026-02-09T00:00:00","date_gmt":"2026-02-09T00:00:00","guid":{"rendered":"https:\/\/wordpress.securinsight.ca\/index.php\/2026\/02\/09\/agents-workers-agents-sdk-v0-4-0-readonly-connections-mcp-security-improvements-x402-v2-migration-and-custom-mcp-oauth-providers-2\/"},"modified":"2026-02-09T00:00:00","modified_gmt":"2026-02-09T00:00:00","slug":"agents-workers-agents-sdk-v0-4-0-readonly-connections-mcp-security-improvements-x402-v2-migration-and-custom-mcp-oauth-providers-2","status":"publish","type":"post","link":"https:\/\/wordpress.securinsight.ca\/index.php\/2026\/02\/09\/agents-workers-agents-sdk-v0-4-0-readonly-connections-mcp-security-improvements-x402-v2-migration-and-custom-mcp-oauth-providers-2\/","title":{"rendered":"Agents, Workers &#8211; Agents SDK v0.4.0: Readonly connections, MCP security improvements, x402 v2 migration, and custom MCP OAuth providers"},"content":{"rendered":"<p>The latest release of the <a href=\"https:\/\/github.com\/cloudflare\/agents\" target=\"_blank\">Agents SDK<\/a> brings readonly connections, MCP protocol and security improvements, x402 payment protocol v2 migration, and the ability to customize OAuth for MCP server connections.<\/p>\n<h4>Readonly connections<\/h4>\n<p>Agents can now restrict WebSocket clients to read-only access, preventing them from modifying agent state. This is useful for dashboards, spectator views, or any scenario where clients should observe but not mutate.<\/p>\n<p>New hooks: <code>shouldConnectionBeReadonly<\/code>, <code>setConnectionReadonly<\/code>, <code>isConnectionReadonly<\/code>. Readonly connections block both client-side <code>setState()<\/code> and mutating <code>@callable()<\/code> methods, and the readonly flag survives hibernation.<\/p>\n<ul>\n<li>\n<p>JavaScript<\/p>\n<div>\n<div>\n<figure>\n<pre data-language=\"js\"><code class=\"language-js\"><div><div><span>class<\/span><span> <\/span><span>MyAgent<\/span><span> <\/span><span>extends<\/span><span> <\/span><span>Agent<\/span><span> <\/span><span>{<\/span><\/div><\/div><div><div><span>  <\/span><span>shouldConnectionBeReadonly<\/span><span>(<\/span><span>connection<\/span><span>)<\/span><span> <\/span><span>{<\/span><\/div><\/div><div><div><span>    <\/span><span>\/\/ Make spectators readonly<\/span><\/div><\/div><div><div><span>    <\/span><span>return<\/span><span> <\/span><span>connection<\/span><span>.<\/span><span>url<\/span><span>.<\/span><span>includes<\/span><span>(<\/span><span>\"spectator\"<\/span><span>)<\/span><span>;<\/span><\/div><\/div><div><div><span>  <\/span><span>}<\/span><\/div><\/div><div><div><span>}<\/span><\/div><\/div><\/code><\/pre>\n<div>\n<div><\/div>\n<\/div>\n<\/figure>\n<\/div><\/div>\n<\/li>\n<li>\n<p>TypeScript<\/p>\n<div>\n<div>\n<figure>\n<pre data-language=\"ts\"><code class=\"language-ts\"><div><div><span>class<\/span><span> <\/span><span>MyAgent<\/span><span> <\/span><span>extends<\/span><span> <\/span><span>Agent<\/span><span> <\/span><span>{<\/span><\/div><\/div><div><div><span>  <\/span><span>shouldConnectionBeReadonly<\/span><span>(<\/span><span>connection<\/span><span>)<\/span><span> <\/span><span>{<\/span><\/div><\/div><div><div><span>    <\/span><span>\/\/ Make spectators readonly<\/span><\/div><\/div><div><div><span>    <\/span><span>return<\/span><span> <\/span><span>connection<\/span><span>.<\/span><span>url<\/span><span>.<\/span><span>includes<\/span><span>(<\/span><span>\"spectator\"<\/span><span>)<\/span><span>;<\/span><\/div><\/div><div><div><span>  <\/span><span>}<\/span><\/div><\/div><div><div><span>}<\/span><\/div><\/div><\/code><\/pre>\n<div>\n<div><\/div>\n<\/div>\n<\/figure>\n<\/div><\/div>\n<\/li>\n<\/ul>\n<h4>Custom MCP OAuth providers<\/h4>\n<p>The new <code>createMcpOAuthProvider<\/code> method on the <code>Agent<\/code> class allows subclasses to override the default OAuth provider used when connecting to MCP servers. This enables custom authentication strategies such as pre-registered client credentials or mTLS, beyond the built-in dynamic client registration.<\/p>\n<ul>\n<li>\n<p>JavaScript<\/p>\n<div>\n<div>\n<figure>\n<pre data-language=\"js\"><code class=\"language-js\"><div><div><span>class<\/span><span> <\/span><span>MyAgent<\/span><span> <\/span><span>extends<\/span><span> <\/span><span>Agent<\/span><span> <\/span><span>{<\/span><\/div><\/div><div><div><span>  <\/span><span>createMcpOAuthProvider<\/span><span>(<\/span><span>callbackUrl<\/span><span>)<\/span><span> <\/span><span>{<\/span><\/div><\/div><div><div><span>    <\/span><span>return<\/span><span> <\/span><span>new<\/span><span> <\/span><span>MyCustomOAuthProvider<\/span><span>(<\/span><span>this<\/span><span>.<\/span><span>ctx<\/span><span>.<\/span><span>storage<\/span><span>,<\/span><span> <\/span><span>this<\/span><span>.<\/span><span>name<\/span><span>,<\/span><span> <\/span><span>callbackUrl<\/span><span>)<\/span><span>;<\/span><\/div><\/div><div><div><span>  <\/span><span>}<\/span><\/div><\/div><div><div><span>}<\/span><\/div><\/div><\/code><\/pre>\n<div>\n<div><\/div>\n<\/div>\n<\/figure>\n<\/div><\/div>\n<\/li>\n<li>\n<p>TypeScript<\/p>\n<div>\n<div>\n<figure>\n<pre data-language=\"ts\"><code class=\"language-ts\"><div><div><span>class<\/span><span> <\/span><span>MyAgent<\/span><span> <\/span><span>extends<\/span><span> <\/span><span>Agent<\/span><span> <\/span><span>{<\/span><\/div><\/div><div><div><span>  <\/span><span>createMcpOAuthProvider<\/span><span>(<\/span><span>callbackUrl<\/span><span>:<\/span><span> <\/span><span>string<\/span><span>)<\/span><span>:<\/span><span> <\/span><span>AgentMcpOAuthProvider<\/span><span> <\/span><span>{<\/span><\/div><\/div><div><div><span>    <\/span><span>return<\/span><span> <\/span><span>new<\/span><span> <\/span><span>MyCustomOAuthProvider<\/span><span>(<\/span><span>this<\/span><span>.<\/span><span>ctx<\/span><span>.<\/span><span>storage<\/span><span>,<\/span><span> <\/span><span>this<\/span><span>.<\/span><span>name<\/span><span>,<\/span><span> <\/span><span>callbackUrl<\/span><span>)<\/span><span>;<\/span><\/div><\/div><div><div><span>  <\/span><span>}<\/span><\/div><\/div><div><div><span>}<\/span><\/div><\/div><\/code><\/pre>\n<div>\n<div><\/div>\n<\/div>\n<\/figure>\n<\/div><\/div>\n<\/li>\n<\/ul>\n<h4>MCP SDK upgrade to 1.26.0<\/h4>\n<p>Upgraded the MCP SDK to 1.26.0 to prevent cross-client response leakage. Stateless MCP Servers should now create a new <code>McpServer<\/code> instance per request instead of sharing a single instance. A guard is added in this version of the MCP SDK which will prevent connection to a Server instance that has already been connected to a transport. Developers will need to modify their code if they declare their <code>McpServer<\/code> instance as a global variable.<\/p>\n<h4>MCP OAuth callback URL security fix<\/h4>\n<p>Added <code>callbackPath<\/code> option to <code>addMcpServer<\/code> to prevent instance name leakage in MCP OAuth callback URLs. When <code>sendIdentityOnConnect<\/code> is <code>false<\/code>, <code>callbackPath<\/code> is now required \u2014 the default callback URL would expose the instance name, undermining the security intent. Also fixes callback request detection to match via the <code>state<\/code> parameter instead of a loose <code>\/callback<\/code> URL substring check, enabling custom callback paths.<\/p>\n<h4>Deprecate <code>onStateUpdate<\/code> in favor of <code>onStateChanged<\/code><\/h4>\n<p><code>onStateChanged<\/code> is a drop-in rename of <code>onStateUpdate<\/code> (same signature, same behavior). <code>onStateUpdate<\/code> still works but emits a one-time console warning per class. <code>validateStateChange<\/code> rejections now propagate a <code>CF_AGENT_STATE_ERROR<\/code> message back to the client.<\/p>\n<h4>x402 v2 migration<\/h4>\n<p>Migrated the x402 MCP payment integration from the legacy <code>x402<\/code> package to <code>@x402\/core<\/code> and <code>@x402\/evm<\/code> v2.<\/p>\n<p><strong>Breaking changes for x402 users:<\/strong><\/p>\n<ul>\n<li>Peer dependencies changed: replace <code>x402<\/code> with <code>@x402\/core<\/code> and <code>@x402\/evm<\/code><\/li>\n<li><code>PaymentRequirements<\/code> type now uses v2 fields (e.g. <code>amount<\/code> instead of <code>maxAmountRequired<\/code>)<\/li>\n<li><code>X402ClientConfig.account<\/code> type changed from <code>viem.Account<\/code> to <code>ClientEvmSigner<\/code> (structurally compatible with <code>privateKeyToAccount()<\/code>)<\/li>\n<\/ul>\n<div>\n<figure>\n<pre data-language=\"bash\"><code class=\"language-bash\"><div><div><span>npm<\/span><span> <\/span><span>uninstall<\/span><span> <\/span><span>x402<\/span><\/div><\/div><div><div><span>npm<\/span><span> <\/span><span>install<\/span><span> <\/span><span>@x402\/core<\/span><span> <\/span><span>@x402\/evm<\/span><\/div><\/div><\/code><\/pre>\n<div>\n<div><\/div>\n<\/div>\n<\/figure>\n<\/div>\n<p>Network identifiers now accept both legacy names and CAIP-2 format:<\/p>\n<div>\n<figure>\n<pre data-language=\"ts\"><code class=\"language-ts\"><div><div><span>\/\/ Legacy name (auto-converted)<\/span><\/div><\/div><div><div><span>{<\/span><\/div><\/div><div><div><span>  <\/span><span>network<\/span><span>:<\/span><span> <\/span><span>\"base-sepolia\"<\/span><span>,<\/span><\/div><\/div><div><div><span>}<\/span><\/div><\/div><div><div>\n<\/div><\/div><div><div><span>\/\/ CAIP-2 format (preferred)<\/span><\/div><\/div><div><div><span>{<\/span><\/div><\/div><div><div><span>  <\/span><span>network<\/span><span>:<\/span><span> <\/span><span>\"eip155:84532\"<\/span><span>,<\/span><\/div><\/div><div><div><span>}<\/span><\/div><\/div><\/code><\/pre>\n<div>\n<div><\/div>\n<\/div>\n<\/figure>\n<\/div>\n<p><strong>Other x402 changes:<\/strong><\/p>\n<ul>\n<li><code>X402ClientConfig.network<\/code> is now optional \u2014 the client auto-selects from available payment requirements<\/li>\n<li>Server-side lazy initialization: facilitator connection is deferred until the first paid tool invocation<\/li>\n<li>Payment tokens support both v2 (<code>PAYMENT-SIGNATURE<\/code>) and v1 (<code>X-PAYMENT<\/code>) HTTP headers<\/li>\n<li>Added <code>normalizeNetwork<\/code> export for converting legacy network names to CAIP-2 format<\/li>\n<li>Re-exports <code>PaymentRequirements<\/code>, <code>PaymentRequired<\/code>, <code>Network<\/code>, <code>FacilitatorConfig<\/code>, and <code>ClientEvmSigner<\/code> from <code>agents\/x402<\/code><\/li>\n<\/ul>\n<h4>Other improvements<\/h4>\n<ul>\n<li>Fix <code>useAgent<\/code> and <code>AgentClient<\/code> crashing when using <code>basePath<\/code> routing<\/li>\n<li>CORS handling delegated to partyserver&#8217;s native support (simpler, more reliable)<\/li>\n<li>Client-side <code>onStateUpdateError<\/code> callback for handling rejected state updates<\/li>\n<\/ul>\n<h4>Upgrade<\/h4>\n<p>To update to the latest version:<\/p>\n<div>\n<figure>\n<pre data-language=\"sh\"><code class=\"language-sh\"><div><div><span>npm<\/span><span> <\/span><span>i<\/span><span> <\/span><span>agents@latest<\/span><\/div><\/div><\/code><\/pre>\n<div>\n<div><\/div>\n<\/div>\n<\/figure>\n<\/div>","protected":false},"excerpt":{"rendered":"<p>The latest release of the Agents SDK brings readonly connections, MCP protocol and security improvements, x402 payment protocol v2 migration, and the ability to customize OAuth for MCP server connections. Readonly connections Agents can now restrict WebSocket clients to read-only access, preventing them from modifying agent state. This is useful for dashboards, spectator views, or [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-212","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/wordpress.securinsight.ca\/index.php\/wp-json\/wp\/v2\/posts\/212","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/wordpress.securinsight.ca\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/wordpress.securinsight.ca\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/wordpress.securinsight.ca\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/wordpress.securinsight.ca\/index.php\/wp-json\/wp\/v2\/comments?post=212"}],"version-history":[{"count":0,"href":"https:\/\/wordpress.securinsight.ca\/index.php\/wp-json\/wp\/v2\/posts\/212\/revisions"}],"wp:attachment":[{"href":"https:\/\/wordpress.securinsight.ca\/index.php\/wp-json\/wp\/v2\/media?parent=212"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/wordpress.securinsight.ca\/index.php\/wp-json\/wp\/v2\/categories?post=212"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/wordpress.securinsight.ca\/index.php\/wp-json\/wp\/v2\/tags?post=212"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}