feat: Add MCP tool titles and hints to all Cloudflare tools (#218)

shelley-cf · Maximo-Guk · web-flow · commit 24dd872b16a0 · 2025-08-13T10:30:26.000-05:00
* feat: Add MCP tool titles and hints to all Cloudflare tools

- Add MCP-compliant tool titles and annotations to 27 tools across 8 files
- Implement readOnlyHint and destructiveHint for intelligent default approval
- Follow MCP specification: 2-5 words, sentence case, active verbs
- Enhanced UX with friendly tool names in MCP clients like Claude.ai
- Enable auto-approval for 15 read-only tools, safety warnings for 4 destructive tools

Files updated:
- d1.tools.ts (5 tools)
- account.tools.ts (2 tools)
- docs-vectorize.tools.ts (2 tools)
- hyperdrive.tools.ts (4 tools)
- kv_namespace.tools.ts (5 tools)
- r2_bucket.tools.ts (4 tools)
- worker.tools.ts (3 tools)
- zone.tools.ts (2 tools)

* Fix param ordering and add changeset

* Bump agents deps

---------

Co-authored-by: Maximo Guk &lt;62088388+Maximo-Guk@users.noreply.github.com&gt;
diff --git a/.changeset/clever-humans-smell.md b/.changeset/clever-humans-smell.md
@@ -0,0 +1,23 @@
+---
+'workers-observability': patch
+'cloudflare-casb-mcp-server': patch
+'cloudflare-browser-mcp-server': patch
+'containers-mcp': patch
+'workers-bindings': patch
+'docs-vectorize': patch
+'workers-builds': patch
+'@repo/eval-tools': patch
+'@repo/mcp-common': patch
+'dns-analytics': patch
+'dex-analysis': patch
+'docs-autorag': patch
+'cloudflare-ai-gateway-mcp-server': patch
+'auditlogs': patch
+'demo-day': patch
+'cloudflare-autorag-mcp-server': patch
+'graphql-mcp-server': patch
+'logpush': patch
+'cloudflare-radar-mcp-server': patch
+---
+
+feat: Add MCP tool titles and hints to all Cloudflare tools
diff --git a/apps/ai-gateway/package.json b/apps/ai-gateway/package.json
@@ -14,10 +14,10 @@
 	"dependencies": {
 		"@cloudflare/workers-oauth-provider": "0.0.5",
 		"@hono/zod-validator": "0.4.3",
-		"@modelcontextprotocol/sdk": "1.13.3",
+		"@modelcontextprotocol/sdk": "1.17.2",
 		"@repo/mcp-common": "workspace:*",
 		"@repo/mcp-observability": "workspace:*",
-		"agents": "0.0.100",
+		"agents": "0.0.113",
 		"cloudflare": "4.2.0",
 		"hono": "4.7.6",
 		"zod": "3.24.2"
diff --git a/apps/auditlogs/package.json b/apps/auditlogs/package.json
@@ -14,10 +14,10 @@
 	"dependencies": {
 		"@cloudflare/workers-oauth-provider": "0.0.5",
 		"@hono/zod-validator": "0.4.3",
-		"@modelcontextprotocol/sdk": "1.13.3",
+		"@modelcontextprotocol/sdk": "1.17.2",
 		"@repo/mcp-common": "workspace:*",
 		"@repo/mcp-observability": "workspace:*",
-		"agents": "0.0.100",
+		"agents": "0.0.113",
 		"cloudflare": "4.2.0",
 		"hono": "4.7.6",
 		"zod": "3.24.2"
diff --git a/apps/autorag/package.json b/apps/autorag/package.json
@@ -14,10 +14,10 @@
 	"dependencies": {
 		"@cloudflare/workers-oauth-provider": "0.0.5",
 		"@hono/zod-validator": "0.4.3",
-		"@modelcontextprotocol/sdk": "1.13.3",
+		"@modelcontextprotocol/sdk": "1.17.2",
 		"@repo/mcp-common": "workspace:*",
 		"@repo/mcp-observability": "workspace:*",
-		"agents": "0.0.100",
+		"agents": "0.0.113",
 		"cloudflare": "4.2.0",
 		"hono": "4.7.6",
 		"zod": "3.24.2"
diff --git a/apps/browser-rendering/package.json b/apps/browser-rendering/package.json
@@ -14,10 +14,10 @@
 	"dependencies": {
 		"@cloudflare/workers-oauth-provider": "0.0.5",
 		"@hono/zod-validator": "0.4.3",
-		"@modelcontextprotocol/sdk": "1.13.3",
+		"@modelcontextprotocol/sdk": "1.17.2",
 		"@repo/mcp-common": "workspace:*",
 		"@repo/mcp-observability": "workspace:*",
-		"agents": "0.0.100",
+		"agents": "0.0.113",
 		"cloudflare": "4.2.0",
 		"hono": "4.7.6",
 		"zod": "3.24.2"
diff --git a/apps/cloudflare-one-casb/package.json b/apps/cloudflare-one-casb/package.json
@@ -14,9 +14,9 @@
 	"dependencies": {
 		"@cloudflare/workers-oauth-provider": "0.0.5",
 		"@hono/zod-validator": "0.4.3",
-		"@modelcontextprotocol/sdk": "1.13.3",
+		"@modelcontextprotocol/sdk": "1.17.2",
 		"@repo/mcp-common": "workspace:*",
-		"agents": "0.0.100",
+		"agents": "0.0.113",
 		"cloudflare": "4.2.0",
 		"hono": "4.7.6",
 		"zod": "3.24.2"
diff --git a/apps/demo-day/package.json b/apps/demo-day/package.json
@@ -11,10 +11,10 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "1.13.3",
+		"@modelcontextprotocol/sdk": "1.17.2",
 		"@repo/mcp-common": "workspace:*",
 		"@repo/mcp-observability": "workspace:*",
-		"agents": "0.0.100",
+		"agents": "0.0.113",
 		"zod": "3.24.2"
 	},
 	"devDependencies": {
diff --git a/apps/dex-analysis/package.json b/apps/dex-analysis/package.json
@@ -15,10 +15,10 @@
 	"dependencies": {
 		"@cloudflare/workers-oauth-provider": "0.0.5",
 		"@hono/zod-validator": "0.4.3",
-		"@modelcontextprotocol/sdk": "1.13.3",
+		"@modelcontextprotocol/sdk": "1.17.2",
 		"@repo/mcp-common": "workspace:*",
 		"@repo/mcp-observability": "workspace:*",
-		"agents": "0.0.100",
+		"agents": "0.0.113",
 		"cloudflare": "4.2.0",
 		"hono": "4.7.6",
 		"jszip": "3.10.1",
diff --git a/apps/dns-analytics/package.json b/apps/dns-analytics/package.json
@@ -14,10 +14,10 @@
 	"dependencies": {
 		"@cloudflare/workers-oauth-provider": "0.0.5",
 		"@hono/zod-validator": "0.4.3",
-		"@modelcontextprotocol/sdk": "1.13.3",
+		"@modelcontextprotocol/sdk": "1.17.2",
 		"@repo/mcp-common": "workspace:*",
 		"@repo/mcp-observability": "workspace:*",
-		"agents": "0.0.100",
+		"agents": "0.0.113",
 		"cloudflare": "4.2.0",
 		"hono": "4.7.6",
 		"zod": "3.24.2"
diff --git a/apps/docs-autorag/package.json b/apps/docs-autorag/package.json
@@ -14,10 +14,10 @@
 	"dependencies": {
 		"@cloudflare/workers-oauth-provider": "0.0.5",
 		"@hono/zod-validator": "0.4.3",
-		"@modelcontextprotocol/sdk": "1.13.3",
+		"@modelcontextprotocol/sdk": "1.17.2",
 		"@repo/mcp-common": "workspace:*",
 		"@repo/mcp-observability": "workspace:*",
-		"agents": "0.0.100",
+		"agents": "0.0.113",
 		"cloudflare": "4.2.0",
 		"hono": "4.7.6",
 		"mime": "4.0.6",
diff --git a/apps/docs-vectorize/package.json b/apps/docs-vectorize/package.json
@@ -14,10 +14,10 @@
 	"dependencies": {
 		"@cloudflare/workers-oauth-provider": "0.0.5",
 		"@hono/zod-validator": "0.4.3",
-		"@modelcontextprotocol/sdk": "1.13.3",
+		"@modelcontextprotocol/sdk": "1.17.2",
 		"@repo/mcp-common": "workspace:*",
 		"@repo/mcp-observability": "workspace:*",
-		"agents": "0.0.100",
+		"agents": "0.0.113",
 		"cloudflare": "4.2.0",
 		"hono": "4.7.6",
 		"mime": "4.0.6",
diff --git a/apps/graphql/package.json b/apps/graphql/package.json
@@ -14,10 +14,10 @@
 	"dependencies": {
 		"@cloudflare/workers-oauth-provider": "0.0.5",
 		"@hono/zod-validator": "0.4.3",
-		"@modelcontextprotocol/sdk": "1.13.3",
+		"@modelcontextprotocol/sdk": "1.17.2",
 		"@repo/mcp-common": "workspace:*",
 		"@repo/mcp-observability": "workspace:*",
-		"agents": "0.0.100",
+		"agents": "0.0.113",
 		"cloudflare": "4.2.0",
 		"hono": "4.7.6",
 		"zod": "3.24.2",
diff --git a/apps/logpush/package.json b/apps/logpush/package.json
@@ -14,10 +14,10 @@
 	"dependencies": {
 		"@cloudflare/workers-oauth-provider": "0.0.5",
 		"@hono/zod-validator": "0.4.3",
-		"@modelcontextprotocol/sdk": "1.13.3",
+		"@modelcontextprotocol/sdk": "1.17.2",
 		"@repo/mcp-common": "workspace:*",
 		"@repo/mcp-observability": "workspace:*",
-		"agents": "0.0.100",
+		"agents": "0.0.113",
 		"cloudflare": "4.2.0",
 		"hono": "4.7.6",
 		"zod": "3.24.2"
diff --git a/apps/radar/package.json b/apps/radar/package.json
@@ -14,10 +14,10 @@
 	"dependencies": {
 		"@cloudflare/workers-oauth-provider": "0.0.5",
 		"@hono/zod-validator": "0.4.3",
-		"@modelcontextprotocol/sdk": "1.13.3",
+		"@modelcontextprotocol/sdk": "1.17.2",
 		"@repo/mcp-common": "workspace:*",
 		"@repo/mcp-observability": "workspace:*",
-		"agents": "0.0.100",
+		"agents": "0.0.113",
 		"cloudflare": "4.2.0",
 		"hono": "4.7.6",
 		"zod": "3.24.2"
diff --git a/apps/sandbox-container/package.json b/apps/sandbox-container/package.json
@@ -22,12 +22,12 @@
 		"@cloudflare/workers-oauth-provider": "0.0.5",
 		"@hono/node-server": "1.13.8",
 		"@hono/zod-validator": "0.4.3",
-		"@modelcontextprotocol/sdk": "1.13.3",
+		"@modelcontextprotocol/sdk": "1.17.2",
 		"@n8n/json-schema-to-zod": "1.1.0",
 		"@repo/eval-tools": "workspace:*",
 		"@repo/mcp-common": "workspace:*",
 		"@repo/mcp-observability": "workspace:*",
-		"agents": "0.0.100",
+		"agents": "0.0.113",
 		"cron-schedule": "5.0.4",
 		"esbuild": "0.25.1",
 		"hono": "4.7.6",
diff --git a/apps/workers-bindings/package.json b/apps/workers-bindings/package.json
@@ -26,12 +26,12 @@
 	},
 	"dependencies": {
 		"@cloudflare/workers-oauth-provider": "0.0.5",
-		"@modelcontextprotocol/sdk": "1.13.3",
+		"@modelcontextprotocol/sdk": "1.17.2",
 		"@n8n/json-schema-to-zod": "1.1.0",
 		"@repo/eval-tools": "workspace:*",
 		"@repo/mcp-common": "workspace:*",
 		"@repo/mcp-observability": "workspace:*",
-		"agents": "0.0.100",
+		"agents": "0.0.113",
 		"ai": "4.3.10",
 		"concurrently": "9.1.2",
 		"hono": "4.7.6",
diff --git a/apps/workers-builds/package.json b/apps/workers-builds/package.json
@@ -14,10 +14,10 @@
 	"dependencies": {
 		"@cloudflare/workers-oauth-provider": "0.0.5",
 		"@hono/zod-validator": "0.4.3",
-		"@modelcontextprotocol/sdk": "1.13.3",
+		"@modelcontextprotocol/sdk": "1.17.2",
 		"@repo/mcp-common": "workspace:*",
 		"@repo/mcp-observability": "workspace:*",
-		"agents": "0.0.100",
+		"agents": "0.0.113",
 		"cloudflare": "4.2.0",
 		"hono": "4.7.6",
 		"zod": "3.24.2"
diff --git a/apps/workers-observability/package.json b/apps/workers-observability/package.json
@@ -15,10 +15,10 @@
 		"@cloudflare/workers-oauth-provider": "0.0.5",
 		"@fast-csv/format": "5.0.2",
 		"@hono/zod-validator": "0.4.3",
-		"@modelcontextprotocol/sdk": "1.13.3",
+		"@modelcontextprotocol/sdk": "1.17.2",
 		"@repo/mcp-common": "workspace:*",
 		"@repo/mcp-observability": "workspace:*",
-		"agents": "0.0.100",
+		"agents": "0.0.113",
 		"cloudflare": "4.2.0",
 		"hono": "4.7.6",
 		"zod": "3.24.2"
diff --git a/packages/eval-tools/package.json b/packages/eval-tools/package.json
@@ -15,7 +15,7 @@
 		"@ai-sdk/google": "1.2.17",
 		"@ai-sdk/openai": "1.3.20",
 		"@cloudflare/vitest-pool-workers": "0.8.14",
-		"agents": "0.0.100",
+		"agents": "0.0.113",
 		"ai": "4.3.10",
 		"ai-gateway-provider": "0.0.6",
 		"workers-ai-provider": "0.3.0",
diff --git a/packages/mcp-common/package.json b/packages/mcp-common/package.json
@@ -14,9 +14,9 @@
 		"@cloudflare/workers-oauth-provider": "0.0.5",
 		"@fast-csv/format": "5.0.2",
 		"@hono/zod-validator": "0.4.3",
-		"@modelcontextprotocol/sdk": "1.13.3",
+		"@modelcontextprotocol/sdk": "1.17.2",
 		"@repo/mcp-observability": "workspace:*",
-		"agents": "0.0.100",
+		"agents": "0.0.113",
 		"cloudflare": "4.2.0",
 		"hono": "4.7.6",
 		"toucan-js": "4.1.1",
diff --git a/packages/mcp-common/src/tools/account.tools.ts b/packages/mcp-common/src/tools/account.tools.ts
@@ -7,51 +7,62 @@ import type { CloudflareMcpAgent } from '../types/cloudflare-mcp-agent.types'
 
 export function registerAccountTools(agent: CloudflareMcpAgent) {
 	// Tool to list all accounts
-	agent.server.tool('accounts_list', 'List all accounts in your Cloudflare account', async () => {
-		try {
-			const results = await handleAccountsList({
-				client: getCloudflareClient(agent.props.accessToken),
-			})
-			// Sort accounts by created_on date (newest first)
-			const accounts = results
-				// order by created_on desc ( newest first )
-				.sort((a, b) => {
-					if (!a.created_on) return 1
-					if (!b.created_on) return -1
-					return new Date(b.created_on).getTime() - new Date(a.created_on).getTime()
-				})
-				// Remove fields not needed by the LLM
-				.map((account) => {
-					return {
-						id: account.id,
-						name: account.name,
-						created_on: account.created_on,
-					}
+	agent.server.tool(
+		'accounts_list',
+		'List all accounts in your Cloudflare account',
+		{},
+		{
+			title: 'List accounts',
+			annotations: {
+				readOnlyHint: true,
+			},
+		},
+		async () => {
+			try {
+				const results = await handleAccountsList({
+					client: getCloudflareClient(agent.props.accessToken),
 				})
+				// Sort accounts by created_on date (newest first)
+				const accounts = results
+					// order by created_on desc ( newest first )
+					.sort((a, b) => {
+						if (!a.created_on) return 1
+						if (!b.created_on) return -1
+						return new Date(b.created_on).getTime() - new Date(a.created_on).getTime()
+					})
+					// Remove fields not needed by the LLM
+					.map((account) => {
+						return {
+							id: account.id,
+							name: account.name,
+							created_on: account.created_on,
+						}
+					})
 
-			return {
-				content: [
-					{
-						type: 'text',
-						text: JSON.stringify({
-							accounts,
-							count: accounts.length,
-						}),
-					},
-				],
-			}
-		} catch (e) {
-			agent.server.recordError(e)
-			return {
-				content: [
-					{
-						type: 'text',
-						text: `Error listing accounts: ${e instanceof Error && e.message}`,
-					},
-				],
+				return {
+					content: [
+						{
+							type: 'text',
+							text: JSON.stringify({
+								accounts,
+								count: accounts.length,
+							}),
+						},
+					],
+				}
+			} catch (e) {
+				agent.server.recordError(e)
+				return {
+					content: [
+						{
+							type: 'text',
+							text: `Error listing accounts: ${e instanceof Error && e.message}`,
+						},
+					],
+				}
 			}
 		}
-	})
+	)
 
 	// Only register set_active_account tool when user token is provided, as it doesn't make sense to expose
 	// this tool for account scoped tokens, given that they're scoped to a single account
@@ -67,6 +78,13 @@ export function registerAccountTools(agent: CloudflareMcpAgent) {
 			{
 				activeAccountIdParam,
 			},
+			{
+				title: 'Set active account',
+				annotations: {
+					readOnlyHint: false,
+					destructiveHint: false,
+				},
+			},
 			async (params) => {
 				try {
 					const { activeAccountIdParam: activeAccountId } = params
diff --git a/packages/mcp-common/src/tools/d1.tools.ts b/packages/mcp-common/src/tools/d1.tools.ts
diff --git a/packages/mcp-common/src/tools/docs-vectorize.tools.ts b/packages/mcp-common/src/tools/docs-vectorize.tools.ts
diff --git a/packages/mcp-common/src/tools/hyperdrive.tools.ts b/packages/mcp-common/src/tools/hyperdrive.tools.ts
diff --git a/packages/mcp-common/src/tools/kv_namespace.tools.ts b/packages/mcp-common/src/tools/kv_namespace.tools.ts
diff --git a/packages/mcp-common/src/tools/r2_bucket.tools.ts b/packages/mcp-common/src/tools/r2_bucket.tools.ts
diff --git a/packages/mcp-common/src/tools/worker.tools.ts b/packages/mcp-common/src/tools/worker.tools.ts
diff --git a/packages/mcp-common/src/tools/zone.tools.ts b/packages/mcp-common/src/tools/zone.tools.ts
diff --git a/packages/mcp-observability/package.json b/packages/mcp-observability/package.json
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
