Cloudflare Workers AI Code Mode: Building Edge Agents with Stateless MCP Handlers
Cloudflare’s Code Mode paradigm fundamentally alters how language models execute tools.
Traditional AI agent frameworks rely on high-overhead JSON schema function calling, requiring multiple request-response round-trips to execute basic sequential operations. Code Mode enables LLMs to write executable TypeScript blocks that invoke Model Context Protocol (MCP) tools directly inside sandboxed edge environments.
Code Mode vs Traditional JSON Function Calling
TRADITIONAL JSON FUNCTION CALLING CLOUDFLARE CODE MODE EXECUTION
┌──────────────────────────────────────┐ ┌──────────────────────────────────────┐
│ LLM Output: `{"name":"tool_a"}` │ │ LLM Output: Executable JS Block │
├──────────────────────────────────────┤ │ `const a = await toolA();` │
│ Client executes & returns JSON result│ │ `const b = await toolB(a);` │
├──────────────────────────────────────┤ ├──────────────────────────────────────┤
│ LLM Output: `{"name":"tool_b"}` │ │ Executed in 1 Edge Turn (0 Extra RTT)│
└──────────────────────────────────────┘ └──────────────────────────────────────┘| Execution Dimension | Traditional JSON Function Calling | Cloudflare Code Mode |
|---|---|---|
| Tool Serialization | Verbose JSON Schemas per turn | Programmatic TypeScript invocation |
| Turn Latency | High (N network round-trips for N tools) | Low (1 edge turn for multi-tool script) |
| Token Overhead | Re-sends tool schemas on every prompt | Single code generation block |
| Tool Chaining | LLM must parse intermediate outputs | Code manipulates data variables directly |
Implementation Guide: Edge Agent with createMcpHandler
import { createMcpHandler } from "@modelcontextprotocol/sdk/v2/server";
import { z } from "zod";
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const handler = createMcpHandler({
name: "edge-code-mode-agent",
version: "1.0.0",
tools: [
{
name: "fetch_vector_embeddings",
description: "Search Cloudflare Vectorize index for context chunks",
parameters: z.object({ query: z.string() }),
execute: async ({ query }) => {
const matches = await env.VECTOR_INDEX.query(query, { topK: 3 });
return { matches };
}
}
]
});
return handler(request);
}
};By removing JSON tool serialization overhead, Cloudflare Code Mode enables edge agents to execute complex multi-step workflows with minimal latency and reduced token consumption.
