Centralize account-ID resolution; upgrade agents/MCP SDK/zod/ai; migrate to registerTool (#384)

* feat: centralize account-id resolution; remove account-management tools

Replace the tool-based account selection (accounts_list + set_active_account,
per-app getActiveAccountId/setActiveAccountId, UserDetails activeAccountId) with a
centralized AccountManager + a CloudflareMCPServer.accountTool() wrapper.

Resolution precedence (per call):
  1. Auth-pinned account — account-scoped token's account, or a single-account OAuth
     token (no account_id param exposed in this case).
  2. cf-account-id request header (user-configured) — multi-account tokens only.
  3. account_id tool argument — auto-appended only for multi-account tokens.

Multi-account credentials get their account list injected into the server initialize
instructions for discovery. All tool error responses now set isError: true.

- New: packages/mcp-common/src/account-manager.ts (3-layer resolver) + account-tool.ts
  (buildAccountTool wrapper core, kept ajv-free for testing) + specs (19 tests).
- CloudflareMCPServer gains accountTool(); collapse dead CloudflareMcpAgentNoAccount layer.
- Migrate all account-scoped shared + per-app tools to accountTool.
- Remove account.tools.ts, account.api.ts, constants.ts, accounts.eval.ts; update READMEs
  and implementation-guides/tools.md.

Supersedes #316.

* chore: upgrade agents 0.13, MCP SDK 1.29, zod 4, ai 6

Bumps across all packages: agents 0.2.19→0.13.3, @modelcontextprotocol/sdk
1.20.2→1.29.0, zod 3.24.2→4.4.3, ai 4.3.10→6.0.193 (+ @ai-sdk/* v3 providers,
ai-gateway-provider 3.1.3).

Migration fixes:
- zod 4: z.record(key, value) explicit key; z.string().ip() -> z.ipv4()/z.ipv6();
  drop removed objectOutputType (use z.infer<z.ZodObject<Shape>>).
- agents 0.13: McpAgent env generic constrained to Cloudflare.Env; api-handler /
  api-token-mode infer the env generic (no `any`).
- MCP SDK 1.29: flatten tool annotations to { title, readOnlyHint, ... } (fixes a
  latent bug where nested annotations were ignored).
- ai 6: eval tooling (LanguageModel, inputSchema, stopWhen/stepCountIs, tool-call input);
  MCPClientManager now takes a storage option.

Typecheck + lint green across all 19 packages. Changeset added for all servers.

* refactor: migrate tool registration to registerTool (MCP SDK 1.29)

The legacy `.tool()` API is deprecated in favour of `.registerTool(name, config, cb)`.

- CloudflareMCPServer now wraps BOTH `tool()` and `registerTool()` for metrics via a shared
  `trackCb` helper, so every registration path is tracked identically.
- accountTool() registers via `registerTool({ description, inputSchema, annotations }, cb)`;
  buildAccountTool's callback is typed as the SDK `ToolCallback<ZodRawShape>`, so the call is
  fully type-checked (removed the `@ts-ignore`).
- Converted all 78 remaining `.tool(...)` call sites across apps + shared tools to
  `.registerTool(...)` with the config-object form (61 in radar, 17 across 8 other files).

Typecheck + lint green across all 19 packages; account-manager + accountTool specs pass.

* refactor: remove @ts-ignore from tool/registerTool override forwarding

The two overrides spread `unknown[]` into the bound original methods (`_tool(name, ...rest)`),
which TS rejects with TS2556 (spread into an overloaded signature without a rest param) — the
forwarding is correct at runtime. Type the bound originals as variadic
`(...args: unknown[]) => ReturnType<McpServer['tool' | 'registerTool']>` so the spread is legal.
No suppression, no `any`. Typecheck + lint green.

* chore: point packages/tools zod pin at stable 4.4.3 (syncpack)

* chore: upgrade dev toolchain for agents 0.13 local dev

agents 0.13 needs a newer local workerd than the pinned wrangler provided
(`cloudflare:workers` `exports`), so bump the dev/test toolchain:
- wrangler 4.10.0 → 4.96.0 (recent workerd; fixes `wrangler dev`)
- esbuild override 0.25.1 → 0.27.3 (required by wrangler 4.96)
- @cloudflare/vitest-pool-workers 0.8.14 → 0.12.0 (newest on esbuild 0.27 that
  keeps the vitest-3 `/config` API; avoids the vitest-4 config-rewrite migration)
- vitest 3.0.9 → 3.2.6, @vitest/ui → 3.2.6

All dev dependencies — no change to deployed runtime. Verified `wrangler dev` boots
the workers-observability server and tools resolve end-to-end; tests 116/116, types,
lint, deps, format all green.

* chore: migrate to vitest 4 + @cloudflare/vitest-pool-workers 0.16

Completes the test-toolchain upgrade (vitest 3.2 → 4.1.8, pool-workers 0.12 → 0.16.11),
using pool-workers' official `vitest-v3-to-v4` codemod + recipes.

- Ran the codemod across all vitest configs: `defineWorkersConfig`/`defineWorkersProject`
  → `defineConfig` from 'vitest/config' with the `cloudflareTest({...})` Vite plugin (the
  `poolOptions.workers` block moves into the plugin). Removed dropped options
  (`singleWorker`, `isolatedStorage`).
- Migrated the workspace: `vitest.workspace.ts` → root `vitest.config.ts` with `test.projects`.
- Added `"type": "module"` to the worker packages (pool-workers 0.16 main entry is ESM-only,
  so `.ts` configs must load as ESM).
- pool-workers 0.16 removed `fetchMock` from `cloudflare:test`: migrated the 4 specs that
  mocked api.cloudflare.com to MSW (per the official request-mocking recipe) — shared
  `src/test/msw-server.ts` + `msw-setup.ts`, `server.use(http.<m>(url, () => HttpResponse...))`.
- tsconfig `types`: `@cloudflare/vitest-pool-workers` → `/types` (cloudflare:test module moved).
- eval-tools: import `env` from `cloudflare:workers` (cloudflare:test `env` is deprecated);
  typed eval vars via a local `EvalEnv`; added missing credentials guard in getAnthropicModel.
- Deduped `@types/node` to 22.15.17 (override + declarations) to collapse a duplicate `vite`
  that made plugin types "unrelated".

All gates green: check:types + check:lint (37/37), tests (116), check:deps, check:format.

* chore(evals): route AI Gateway via BYOK unified provider; connect over /mcp

- test-models: use ai-gateway-provider createUnified() with the gateway's
  stored (BYOK) keys instead of an empty per-provider apiKey, fixing the
  'Incorrect API key' failures. Judge: gpt-5.4-nano; subjects: gpt-5.4-mini,
  gpt-4.1, and workers-ai/@cf/moonshotai/kimi-k2.6.
- drop now-unused providers (@ai-sdk/openai, @ai-sdk/anthropic, @ai-sdk/google,
  workers-ai-provider) from eval-tools.
- eval clients connect to /mcp (token-mode servers only serve /mcp, not /sse).
- bump ai 6.0.193 -> 6.0.194.

* refactor: remove dormant UserDetails durable object

The UserDetails DO existed only to persist activeAccountId across sessions
(added in #85) for the old set_active_account / accounts_list flow. Account
resolution is now derived per-request (auth-pinned -> cf-account-id header ->
account_id arg), so nothing reads or writes it — getUserDetails has no callers.

- delete user_details.do.ts and remove the USER_DETAILS binding, export, and
  Env type from all 13 account-scoped apps (dev + staging + production).
- add a deleted_classes DO migration (tag v2) to the two owning workers
  (workers-observability, workers-builds) so the namespace is torn down.
- strip the dead commented-out tool blocks in r2_bucket.tools.ts and
  hyperdrive.tools.ts (they referenced the removed getActiveAccountId API).
- regenerate worker-configuration.d.ts across apps (drops USER_DETAILS).

* fix(types): make worker types current; drop --include-env=false

CI typecheck broke after regenerating worker-configuration.d.ts to the
wrangler 4.96 / workerd 1.20260529 runtime types. Fixes:

- remove '--include-env=false' from every app's 'types' script (and the
  run-wrangler-types helper). Under the new wrangler that flag also strips the
  global 'interface Env' the app/test code relies on (getEnv<Env>, McpAgent<Env>,
  vitest TestEnv extends Env); without it the global Env is emitted again.
- regenerate packages/mcp-common/worker-configuration.d.ts (was stuck at
  workerd 1.20250409, predating embeddinggemma in AiModels) so the docs-vectorize
  embeddings tool typechecks; drop the now-unnecessary @ts-expect-error directives.
- docs-* and sandbox-container: drop 'public' from the 'ctx: DurableObjectState'
  constructor params — the new DurableObjectState<unknown> default conflicts with
  the McpAgent/DurableObject base's DurableObjectState<{}>; inheriting it avoids
  the redeclaration (matches every other app).
- api-token-mode: ExecutionContext.props is now readonly; assign auth props via a
  typed mutable view (runtime sets props before serve()).

* refactor: remove dead activeAccountId agent state

Vestigial leftover from the account-id centralization: 'activeAccountId' was
still declared in each agent's State (and one initialState) but never read or
written — account resolution is now derived per-request via AccountManager.

- drop the field from all 13 account-scoped apps' State (and workers-bindings'
  initialState); workers-builds keeps its still-used activeBuildUUID/activeWorkerId.
- mcp-common CloudflareMCPAgentState is now an empty base (Record<string, unknown>)
  so servers with their own state (workers-builds) stay assignable to CloudflareMcpAgent.

Author: mattzcarey

.changeset/centralize-account-id-resolution.md

@@ -0,0 +1,32 @@
+---
+'cloudflare-ai-gateway-mcp-server': minor
+'cloudflare-autorag-mcp-server': minor
+'cloudflare-browser-mcp-server': minor
+'cloudflare-casb-mcp-server': minor
+'cloudflare-radar-mcp-server': minor
+'graphql-mcp-server': minor
+'workers-observability': minor
+'workers-bindings': minor
+'workers-builds': minor
+'dex-analysis': minor
+'dns-analytics': minor
+'auditlogs': minor
+'logpush': minor
+---
+
+Centralize Cloudflare account resolution and remove the account-management tools.
+
+The `accounts_list` and `set_active_account` tools are removed. Account scoping is now
+resolved automatically by an `AccountManager` (via the new `server.accountTool()`
+registration), in priority order:
+
+1. **Auth-pinned account** — an account-scoped API token's account, or an OAuth token with a
+   single account, is used automatically (no `account_id` parameter is exposed).
+2. **`cf-account-id` request header** — for tokens that can access multiple accounts, set this
+   header in your MCP client config to pick an account.
+3. **`account_id` tool argument** — for multi-account tokens, account-scoped tools expose an
+   optional `account_id` parameter; when omitted (and no header is set) the tool returns an
+   error listing the accounts you can use. Multi-account credentials also list their accounts
+   in the server's `initialize` instructions.
+
+All tool error responses now set `isError: true` so clients can distinguish failures.

.changeset/upgrade-agents-mcp-sdk-zod-ai.md

@@ -0,0 +1,31 @@
+---
+'cloudflare-ai-gateway-mcp-server': patch
+'cloudflare-autorag-mcp-server': patch
+'cloudflare-browser-mcp-server': patch
+'cloudflare-casb-mcp-server': patch
+'cloudflare-radar-mcp-server': patch
+'graphql-mcp-server': patch
+'workers-observability': patch
+'workers-bindings': patch
+'workers-builds': patch
+'containers-mcp': patch
+'dex-analysis': patch
+'dns-analytics': patch
+'docs-ai-search': patch
+'docs-autorag': patch
+'docs-vectorize': patch
+'auditlogs': patch
+'logpush': patch
+'demo-day': patch
+---
+
+Upgrade core dependencies: `agents` 0.2.19 → 0.13.3, `@modelcontextprotocol/sdk` 1.20.2 →
+1.29.0, `zod` 3 → 4, and `ai` 4 → 6.
+
+No user-facing tool or behavior changes. Internal adjustments for the new versions:
+- `zod` 4: `z.record(...)` now takes an explicit key schema; `z.string().ip()` replaced with
+  `z.ipv4()`/`z.ipv6()` validation; dropped the removed `objectOutputType` helper.
+- `agents` 0.13: `McpAgent` env generic is constrained to `Cloudflare.Env`.
+- MCP SDK 1.29: tool `annotations` hints must be flat (`{ title, readOnlyHint, ... }`) — fixes a
+  latent bug where nested hints were silently ignored.
+- `ai` 6: eval tooling updated (`LanguageModel`, `inputSchema`, `stopWhen`/`stepCountIs`, tool-call `input`).

.syncpackrc.cjs

@@ -24,7 +24,7 @@ const config = {
 		{
 			label: 'pin vitest compatible with @cloudflare/vitest-pool-workers',
 			dependencies: ['vitest', '@vitest/ui'],
-			pinVersion: '3.0.9',
+			pinVersion: '4.1.8',
 		},
 		{
 			label: 'pin typescript for eslint',
@@ -48,7 +48,7 @@ const config = {
 		{
 			label: 'use zod v4 in packages/tools',
 			dependencies: ['zod'],
-			pinVersion: '4.0.0-beta.20250505T195954',
+			pinVersion: '4.4.3',
 			packages: ['@repo/tools'],
 		},
 	],

apps/ai-gateway/README.md

@@ -18,7 +18,7 @@ Currently available tools:
 | `get_log_request_body`  | Retrieves the request body associated with a specific log in a gateway.                                                             |
 | `get_log_response_body` | Retrieves the response body associated with a specific log in a gateway.                                                            |
 
-**Note:** To use these tools, ensure you have an active account set. If not, use `accounts_list` to list your accounts and `set_active_account` to set one as active.
+**Note:** These tools are account-scoped. Single-account credentials (and account-scoped API tokens) are detected automatically. If your credentials can access multiple accounts, pass `account_id` to the tool, or set a `cf-account-id` request header in your MCP client config.
 
 This MCP server is still a work in progress, and we plan to add more tools in the future.
 

apps/ai-gateway/package.json

@@ -8,26 +8,27 @@
 		"deploy": "run-wrangler-deploy",
 		"dev": "wrangler dev",
 		"start": "wrangler dev",
-		"types": "wrangler types --include-env=false",
+		"types": "wrangler types",
 		"test": "vitest run"
 	},
 	"dependencies": {
 		"@cloudflare/workers-oauth-provider": "0.4.0",
 		"@hono/zod-validator": "0.4.3",
-		"@modelcontextprotocol/sdk": "1.20.2",
+		"@modelcontextprotocol/sdk": "1.29.0",
 		"@repo/mcp-common": "workspace:*",
 		"@repo/mcp-observability": "workspace:*",
-		"agents": "0.2.19",
+		"agents": "0.13.3",
 		"cloudflare": "4.2.0",
 		"hono": "4.7.6",
-		"zod": "3.24.2"
+		"zod": "4.4.3"
 	},
 	"devDependencies": {
-		"@cloudflare/vitest-pool-workers": "0.8.14",
-		"@types/node": "22.14.1",
+		"@cloudflare/vitest-pool-workers": "0.16.11",
+		"@types/node": "22.15.17",
 		"prettier": "3.5.3",
 		"typescript": "5.5.4",
-		"vitest": "3.0.9",
-		"wrangler": "4.10.0"
-	}
+		"vitest": "4.1.8",
+		"wrangler": "4.96.0"
+	},
+	"type": "module"
 }

apps/ai-gateway/src/ai-gateway.app.ts

@@ -1,17 +1,16 @@
 import OAuthProvider from '@cloudflare/workers-oauth-provider'
 import { McpAgent } from 'agents/mcp'
 
+import { AccountManager } from '@repo/mcp-common/src/account-manager'
 import { handleApiTokenMode, isApiTokenRequest } from '@repo/mcp-common/src/api-token-mode'
 import {
 	createAuthHandlers,
 	handleTokenExchangeCallback,
 } from '@repo/mcp-common/src/cloudflare-oauth-handler'
-import { getUserDetails, UserDetails } from '@repo/mcp-common/src/durable-objects/user_details.do'
 import { getEnv } from '@repo/mcp-common/src/env'
 import { getProps } from '@repo/mcp-common/src/get-props'
 import { RequiredScopes } from '@repo/mcp-common/src/scopes'
 import { CloudflareMCPServer } from '@repo/mcp-common/src/server'
-import { registerAccountTools } from '@repo/mcp-common/src/tools/account.tools'
 
 import { MetricsTracker } from '../../../packages/mcp-observability/src'
 import { registerAIGatewayTools } from './tools/ai-gateway.tools'
@@ -21,8 +20,6 @@ import type { Env } from './ai-gateway.context'
 
 const env = getEnv<Env>()
 
-export { UserDetails }
-
 const metrics = new MetricsTracker(env.MCP_METRICS, {
 	name: env.MCP_SERVER_NAME,
 	version: env.MCP_SERVER_VERSION,
@@ -31,7 +28,7 @@ const metrics = new MetricsTracker(env.MCP_METRICS, {
 // Context from the auth process, encrypted & stored in the auth token
 // and provided to the DurableMCP as this.props
 type Props = AuthProps
-type State = { activeAccountId: string | null }
+type State = Record<string, never>
 
 export class AIGatewayMCP extends McpAgent<Env, State, Props> {
 	_server: CloudflareMCPServer | undefined
@@ -54,6 +51,7 @@ export class AIGatewayMCP extends McpAgent<Env, State, Props> {
 		// TODO: Probably we'll want to track account tokens usage through an account identifier at some point
 		const props = getProps(this)
 		const userId = props.type === 'user_token' ? props.user.id : undefined
+		const accountManager = new AccountManager(props)
 
 		this.server = new CloudflareMCPServer({
 			userId,
@@ -62,44 +60,13 @@ export class AIGatewayMCP extends McpAgent<Env, State, Props> {
 				name: this.env.MCP_SERVER_NAME,
 				version: this.env.MCP_SERVER_VERSION,
 			},
+			accountManager,
+			options: { instructions: accountManager.instructionsSuffix() },
 		})
 
-		registerAccountTools(this)
-
 		// Register Cloudflare Log Push tools
 		registerAIGatewayTools(this)
 	}
-
-	async getActiveAccountId() {
-		try {
-			const props = getProps(this)
-			// account tokens are scoped to one account
-			if (props.type === 'account_token') {
-				return props.account.id
-			}
-			// Get UserDetails Durable Object based off the userId and retrieve the activeAccountId from it
-			// we do this so we can persist activeAccountId across sessions
-			const userDetails = getUserDetails(env, props.user.id)
-			return await userDetails.getActiveAccountId()
-		} catch (e) {
-			this.server.recordError(e)
-			return null
-		}
-	}
-
-	async setActiveAccountId(accountId: string) {
-		try {
-			const props = getProps(this)
-			// account tokens are scoped to one account
-			if (props.type === 'account_token') {
-				return
-			}
-			const userDetails = getUserDetails(env, props.user.id)
-			await userDetails.setActiveAccountId(accountId)
-		} catch (e) {
-			this.server.recordError(e)
-		}
-	}
 }
 
 const AIGatewayScopes = {

apps/ai-gateway/src/ai-gateway.context.ts

@@ -1,4 +1,3 @@
-import type { UserDetails } from '@repo/mcp-common/src/durable-objects/user_details.do'
 import type { AIGatewayMCP } from './ai-gateway.app'
 
 export interface Env {
@@ -10,7 +9,6 @@ export interface Env {
 	CLOUDFLARE_CLIENT_ID: string
 	CLOUDFLARE_CLIENT_SECRET: string
 	MCP_OBJECT: DurableObjectNamespace<AIGatewayMCP>
-	USER_DETAILS: DurableObjectNamespace<UserDetails>
 	MCP_METRICS: AnalyticsEngineDataset
 	DEV_DISABLE_OAUTH: string
 	DEV_CLOUDFLARE_API_TOKEN: string