Drop the experimental on createMcpHandler (#603)

* refactor: rename experimental_createMcpHandler to createMcpHandler and add deprecation warning

* Create two-deers-help.md

* Update two-deers-help.md

---------

Co-authored-by: Sunil Pai <spai@cloudflare.com>

Author: mattzcarey

.changeset/two-deers-help.md

@@ -0,0 +1,5 @@
+---
+"agents": patch
+---
+
+Drop the experimental\_ prefix on createMcpHandler

examples/mcp-worker-authenticated/src/index.ts

@@ -1,7 +1,4 @@
-import {
-  experimental_createMcpHandler as createMcpHandler,
-  getMcpAuthContext
-} from "agents/mcp";
+import { createMcpHandler, getMcpAuthContext } from "agents/mcp";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { OAuthProvider } from "@cloudflare/workers-oauth-provider";

examples/mcp-worker/README.md

@@ -1,6 +1,6 @@
 # MCP Worker Example
 
-This example demonstrates how to use `experimental_createMcpHandler` to create an unauthenticated stateless MCP server.
+This example demonstrates how to use `createMcpHandler` to create an unauthenticated stateless MCP server.
 
 This is THE simplest way to get started with MCP on Cloudflare.
 

examples/mcp-worker/src/index.ts

@@ -1,4 +1,4 @@
-import { experimental_createMcpHandler as createMcpHandler } from "agents/mcp";
+import { createMcpHandler } from "agents/mcp";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 

packages/agents/src/mcp/handler.ts

@@ -35,7 +35,7 @@ export type OAuthExecutionContext = ExecutionContext & {
   props?: Record<string, unknown>;
 };
 
-export function experimental_createMcpHandler(
+export function createMcpHandler(
   server: McpServer | Server,
   options: CreateMcpHandlerOptions = {}
 ): (
@@ -92,3 +92,25 @@ export function experimental_createMcpHandler(
     }
   };
 }
+
+let didWarnAboutExperimentalCreateMcpHandler = false;
+
+/**
+ * @deprecated This has been renamed to createMcpHandler, and experimental_createMcpHandler will be removed in the next major version
+ */
+export function experimental_createMcpHandler(
+  server: McpServer | Server,
+  options: CreateMcpHandlerOptions = {}
+): (
+  request: Request,
+  env: unknown,
+  ctx: ExecutionContext
+) => Promise<Response> {
+  if (!didWarnAboutExperimentalCreateMcpHandler) {
+    didWarnAboutExperimentalCreateMcpHandler = true;
+    console.warn(
+      "experimental_createMcpHandler is deprecated, use createMcpHandler instead. experimental_createMcpHandler will be removed in the next major version."
+    );
+  }
+  return createMcpHandler(server, options);
+}

packages/agents/src/mcp/index.ts

@@ -448,6 +448,7 @@ export type {
 } from "./client";
 
 export {
+  createMcpHandler,
   experimental_createMcpHandler,
   type CreateMcpHandlerOptions,
   type OAuthExecutionContext