feat(plugin-mcp): migrate from @vercel/mcp-adapter to mcp-handler (#15661)

kendelljoseph · web-flow · commit 24025fdaf155 · 2026-02-18T04:35:41.000Z
- Replace deprecated @vercel/mcp-adapter with mcp-handler
- Bump @modelcontextprotocol/sdk from ~1.24.0 to 1.25.2 to address a
security vulnerability.
- Migrate all server.tool() calls to the new server.registerTool() API
- Expose disableSse, onEvent, and redisUrl handler options. 
- Add integration tests for the onEvent callback.
diff --git a/packages/plugin-mcp/package.json b/packages/plugin-mcp/package.json
@@ -48,10 +48,10 @@
     "pack:plugin": "pnpm build && pnpm pack"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "~1.24.0",
+    "@modelcontextprotocol/sdk": "1.25.2",
     "@types/json-schema": "7.0.15",
-    "@vercel/mcp-adapter": "^1.0.0",
     "json-schema-to-zod": "2.6.1",
+    "mcp-handler": "^1.0.7",
     "zod": "^3.25.50"
   },
   "devDependencies": {
diff --git a/packages/plugin-mcp/src/mcp/getMcpHandler.ts b/packages/plugin-mcp/src/mcp/getMcpHandler.ts
@@ -1,6 +1,6 @@
 import type { JSONSchema4 } from 'json-schema'
 
-import { createMcpHandler } from '@vercel/mcp-adapter'
+import { createMcpHandler } from 'mcp-handler'
 import { join } from 'path'
 import { APIError, configToJSONSchema, type PayloadRequest, type TypedUser } from 'payload'
 
@@ -260,10 +260,12 @@ export const getMCPHandler = (
             isToolEnabled,
             tool.name,
             () =>
-              server.tool(
+              server.registerTool(
                 tool.name,
-                tool.description,
-                tool.parameters,
+                {
+                  description: tool.description,
+                  inputSchema: tool.parameters,
+                },
                 payloadToolHandler(tool.handler),
               ),
             payload,
@@ -507,9 +509,10 @@ export const getMCPHandler = (
       },
       {
         basePath: MCPHandlerOptions.basePath || payload.config.routes?.api || '/api',
+        disableSse: MCPHandlerOptions.disableSse ?? true,
         maxDuration: MCPHandlerOptions.maxDuration || 60,
-        // INFO: Disabled until developer clarity is reached for server side streaming and we have an auth pattern for all SSE patterns
-        // redisUrl: MCPHandlerOptions.redisUrl || process.env.REDIS_URL,
+        onEvent: MCPHandlerOptions.onEvent,
+        redisUrl: MCPHandlerOptions.redisUrl,
         verboseLogs: useVerboseLogs,
       },
     )
diff --git a/packages/plugin-mcp/src/mcp/tools/auth/auth.ts b/packages/plugin-mcp/src/mcp/tools/auth/auth.ts
@@ -58,10 +58,12 @@ export const authTool = (server: McpServer, req: PayloadRequest, verboseLogs: bo
     }
   }
 
-  server.tool(
+  server.registerTool(
     'auth',
-    toolSchemas.auth.description,
-    toolSchemas.auth.parameters.shape,
+    {
+      description: toolSchemas.auth.description,
+      inputSchema: toolSchemas.auth.parameters.shape,
+    },
     async ({ headers }) => {
       return await tool(headers)
     },
diff --git a/packages/plugin-mcp/src/mcp/tools/auth/forgotPassword.ts b/packages/plugin-mcp/src/mcp/tools/auth/forgotPassword.ts
@@ -57,10 +57,12 @@ export const forgotPasswordTool = (
     }
   }
 
-  server.tool(
+  server.registerTool(
     'forgotPassword',
-    toolSchemas.forgotPassword.description,
-    toolSchemas.forgotPassword.parameters.shape,
+    {
+      description: toolSchemas.forgotPassword.description,
+      inputSchema: toolSchemas.forgotPassword.parameters.shape,
+    },
     async ({ collection, disableEmail, email }) => {
       return await tool(collection, email, disableEmail)
     },
diff --git a/packages/plugin-mcp/src/mcp/tools/auth/login.ts b/packages/plugin-mcp/src/mcp/tools/auth/login.ts
@@ -59,10 +59,12 @@ export const loginTool = (server: McpServer, req: PayloadRequest, verboseLogs: b
     }
   }
 
-  server.tool(
+  server.registerTool(
     'login',
-    toolSchemas.login.description,
-    toolSchemas.login.parameters.shape,
+    {
+      description: toolSchemas.login.description,
+      inputSchema: toolSchemas.login.parameters.shape,
+    },
     async ({ collection, depth, email, overrideAccess, password, showHiddenFields }) => {
       return await tool(collection, email, password, depth, overrideAccess, showHiddenFields)
     },
diff --git a/packages/plugin-mcp/src/mcp/tools/auth/resetPassword.ts b/packages/plugin-mcp/src/mcp/tools/auth/resetPassword.ts
@@ -48,10 +48,12 @@ export const resetPasswordTool = (server: McpServer, req: PayloadRequest, verbos
     }
   }
 
-  server.tool(
+  server.registerTool(
     'resetPassword',
-    toolSchemas.resetPassword.description,
-    toolSchemas.resetPassword.parameters.shape,
+    {
+      description: toolSchemas.resetPassword.description,
+      inputSchema: toolSchemas.resetPassword.parameters.shape,
+    },
     async ({ collection, password, token }) => {
       return await tool(collection, token, password)
     },
diff --git a/packages/plugin-mcp/src/mcp/tools/auth/unlock.ts b/packages/plugin-mcp/src/mcp/tools/auth/unlock.ts
@@ -51,10 +51,12 @@ export const unlockTool = (server: McpServer, req: PayloadRequest, verboseLogs:
     }
   }
 
-  server.tool(
+  server.registerTool(
     'unlock',
-    toolSchemas.unlock.description,
-    toolSchemas.unlock.parameters.shape,
+    {
+      description: toolSchemas.unlock.description,
+      inputSchema: toolSchemas.unlock.parameters.shape,
+    },
     async ({ collection, email }) => {
       return await tool(collection, email)
     },
diff --git a/packages/plugin-mcp/src/mcp/tools/auth/verify.ts b/packages/plugin-mcp/src/mcp/tools/auth/verify.ts
@@ -44,10 +44,12 @@ export const verifyTool = (server: McpServer, req: PayloadRequest, verboseLogs:
     }
   }
 
-  server.tool(
+  server.registerTool(
     'verify',
-    toolSchemas.verify.description,
-    toolSchemas.verify.parameters.shape,
+    {
+      description: toolSchemas.verify.description,
+      inputSchema: toolSchemas.verify.parameters.shape,
+    },
     async ({ collection, token }) => {
       return await tool(collection, token)
     },
diff --git a/packages/plugin-mcp/src/mcp/tools/collection/create.ts b/packages/plugin-mcp/src/mcp/tools/collection/create.ts
@@ -225,10 +225,12 @@ export const createCollectionTool = (
     }
   }
 
-  server.tool(
+  server.registerTool(
     'createCollection',
-    toolSchemas.createCollection.description,
-    toolSchemas.createCollection.parameters.shape,
+    {
+      description: toolSchemas.createCollection.description,
+      inputSchema: toolSchemas.createCollection.parameters.shape,
+    },
     async ({ collectionDescription, collectionName, fields, hasUpload }) => {
       return await tool(collectionName, collectionDescription, fields, hasUpload)
     },
diff --git a/packages/plugin-mcp/src/mcp/tools/collection/delete.ts b/packages/plugin-mcp/src/mcp/tools/collection/delete.ts
@@ -216,10 +216,12 @@ export const deleteCollectionTool = (
     }
   }
 
-  server.tool(
+  server.registerTool(
     'deleteCollection',
-    toolSchemas.deleteCollection.description,
-    toolSchemas.deleteCollection.parameters.shape,
+    {
+      description: toolSchemas.deleteCollection.description,
+      inputSchema: toolSchemas.deleteCollection.parameters.shape,
+    },
     ({ collectionName, confirmDeletion, updateConfig }) => {
       return tool(collectionName, confirmDeletion, updateConfig)
     },
diff --git a/packages/plugin-mcp/src/mcp/tools/collection/find.ts b/packages/plugin-mcp/src/mcp/tools/collection/find.ts
@@ -211,10 +211,12 @@ export const findCollectionTool = (
     }
   }
 
-  server.tool(
+  server.registerTool(
     'findCollections',
-    toolSchemas.findCollections.description,
-    toolSchemas.findCollections.parameters.shape,
+    {
+      description: toolSchemas.findCollections.description,
+      inputSchema: toolSchemas.findCollections.parameters.shape,
+    },
     ({ collectionName, includeContent, includeCount }) => {
       return tool(collectionName, includeContent, includeCount)
     },
diff --git a/packages/plugin-mcp/src/mcp/tools/collection/update.ts b/packages/plugin-mcp/src/mcp/tools/collection/update.ts
@@ -277,10 +277,12 @@ export const updateCollectionTool = (
     }
   }
 
-  server.tool(
+  server.registerTool(
     'updateCollection',
-    toolSchemas.updateCollection.description,
-    toolSchemas.updateCollection.parameters.shape,
+    {
+      description: toolSchemas.updateCollection.description,
+      inputSchema: toolSchemas.updateCollection.parameters.shape,
+    },
     async (args) => {
       return await tool(args)
     },
diff --git a/packages/plugin-mcp/src/mcp/tools/config/find.ts b/packages/plugin-mcp/src/mcp/tools/config/find.ts
@@ -115,10 +115,12 @@ export const findConfigTool = (
     }
   }
 
-  server.tool(
+  server.registerTool(
     'findConfig',
-    toolSchemas.findConfig.description,
-    toolSchemas.findConfig.parameters.shape,
+    {
+      description: toolSchemas.findConfig.description,
+      inputSchema: toolSchemas.findConfig.parameters.shape,
+    },
     ({ includeMetadata }) => {
       return tool(includeMetadata)
     },
diff --git a/packages/plugin-mcp/src/mcp/tools/config/update.ts b/packages/plugin-mcp/src/mcp/tools/config/update.ts
@@ -271,10 +271,12 @@ export const updateConfigTool = (
     }
   }
 
-  server.tool(
+  server.registerTool(
     'updateConfig',
-    toolSchemas.updateConfig.description,
-    toolSchemas.updateConfig.parameters.shape,
+    {
+      description: toolSchemas.updateConfig.description,
+      inputSchema: toolSchemas.updateConfig.parameters.shape,
+    },
     (args) => {
       return tool(args)
     },
diff --git a/packages/plugin-mcp/src/mcp/tools/global/find.ts b/packages/plugin-mcp/src/mcp/tools/global/find.ts
@@ -114,10 +114,12 @@ ${JSON.stringify(result, null, 2)}
   }
 
   if (globals?.[globalSlug]?.enabled) {
-    server.tool(
+    server.registerTool(
       `find${globalSlug.charAt(0).toUpperCase() + toCamelCase(globalSlug).slice(1)}`,
-      `${toolSchemas.findGlobal.description.trim()}\n\n${globals?.[globalSlug]?.description || ''}`,
-      toolSchemas.findGlobal.parameters.shape,
+      {
+        description: `${toolSchemas.findGlobal.description.trim()}\n\n${globals?.[globalSlug]?.description || ''}`,
+        inputSchema: toolSchemas.findGlobal.parameters.shape,
+      },
       async ({ depth, fallbackLocale, locale, select }) => {
         return await tool(depth, locale, fallbackLocale, select)
       },
diff --git a/packages/plugin-mcp/src/mcp/tools/global/update.ts b/packages/plugin-mcp/src/mcp/tools/global/update.ts
@@ -176,10 +176,12 @@ ${JSON.stringify(result, null, 2)}
         ),
     })
 
-    server.tool(
+    server.registerTool(
       `update${globalSlug.charAt(0).toUpperCase() + toCamelCase(globalSlug).slice(1)}`,
-      `${toolSchemas.updateGlobal.description.trim()}\n\n${globals?.[globalSlug]?.description || ''}`,
-      updateGlobalSchema.shape,
+      {
+        description: `${toolSchemas.updateGlobal.description.trim()}\n\n${globals?.[globalSlug]?.description || ''}`,
+        inputSchema: updateGlobalSchema.shape,
+      },
       async (params: Record<string, unknown>) => {
         const { depth, draft, fallbackLocale, locale, select, ...rest } = params
         const data = JSON.stringify(rest)
diff --git a/packages/plugin-mcp/src/mcp/tools/job/create.ts b/packages/plugin-mcp/src/mcp/tools/job/create.ts
@@ -401,10 +401,12 @@ export const createJobTool = (
     }
   }
 
-  server.tool(
+  server.registerTool(
     'createJob',
-    'Creates a new Payload job (task or workflow) with specified configuration',
-    toolSchemas.createJob.parameters.shape,
+    {
+      description: 'Creates a new Payload job (task or workflow) with specified configuration',
+      inputSchema: toolSchemas.createJob.parameters.shape,
+    },
     async (args) => {
       return tool(
         args.jobName,
diff --git a/packages/plugin-mcp/src/mcp/tools/job/run.ts b/packages/plugin-mcp/src/mcp/tools/job/run.ts
@@ -177,10 +177,12 @@ export const runJobTool = (server: McpServer, req: PayloadRequest, verboseLogs:
     }
   }
 
-  server.tool(
+  server.registerTool(
     'runJob',
-    'Runs a Payload job with specified input data and queue options',
-    toolSchemas.runJob.parameters.shape,
+    {
+      description: 'Runs a Payload job with specified input data and queue options',
+      inputSchema: toolSchemas.runJob.parameters.shape,
+    },
     async (args) => {
       const { delay, input, jobSlug, priority, queue } = args
       return await tool(jobSlug, input, queue, priority, delay)
diff --git a/packages/plugin-mcp/src/mcp/tools/job/update.ts b/packages/plugin-mcp/src/mcp/tools/job/update.ts
@@ -291,10 +291,13 @@ export const updateJobTool = (
     }
   }
 
-  server.tool(
+  server.registerTool(
     'updateJob',
-    'Updates an existing Payload job with new configuration, schema, or handler code',
-    toolSchemas.updateJob.parameters.shape,
+    {
+      description:
+        'Updates an existing Payload job with new configuration, schema, or handler code',
+      inputSchema: toolSchemas.updateJob.parameters.shape,
+    },
     async (args) => {
       const {
         configUpdate,
diff --git a/packages/plugin-mcp/src/mcp/tools/resource/create.ts b/packages/plugin-mcp/src/mcp/tools/resource/create.ts
@@ -181,10 +181,12 @@ ${JSON.stringify(result, null, 2)}
         ),
     })
 
-    server.tool(
+    server.registerTool(
       `create${collectionSlug.charAt(0).toUpperCase() + toCamelCase(collectionSlug).slice(1)}`,
-      `${collections?.[collectionSlug]?.description || toolSchemas.createResource.description.trim()}`,
-      createResourceSchema.shape,
+      {
+        description: `${collections?.[collectionSlug]?.description || toolSchemas.createResource.description.trim()}`,
+        inputSchema: createResourceSchema.shape,
+      },
       async (params: Record<string, unknown>) => {
         const { depth, draft, fallbackLocale, locale, select, ...fieldData } = params
         const data = JSON.stringify(fieldData)
diff --git a/packages/plugin-mcp/src/mcp/tools/resource/delete.ts b/packages/plugin-mcp/src/mcp/tools/resource/delete.ts
@@ -204,10 +204,12 @@ ${JSON.stringify(errors, null, 2)}
   }
 
   if (collections?.[collectionSlug]?.enabled) {
-    server.tool(
+    server.registerTool(
       `delete${collectionSlug.charAt(0).toUpperCase() + toCamelCase(collectionSlug).slice(1)}`,
-      `${collections?.[collectionSlug]?.description || toolSchemas.deleteResource.description.trim()}`,
-      toolSchemas.deleteResource.parameters.shape,
+      {
+        description: `${collections?.[collectionSlug]?.description || toolSchemas.deleteResource.description.trim()}`,
+        inputSchema: toolSchemas.deleteResource.parameters.shape,
+      },
       async ({ id, depth, fallbackLocale, locale, where }) => {
         return await tool(id, where, depth, locale, fallbackLocale)
       },
diff --git a/packages/plugin-mcp/src/mcp/tools/resource/find.ts b/packages/plugin-mcp/src/mcp/tools/resource/find.ts
@@ -221,10 +221,12 @@ Page: ${result.page} of ${result.totalPages}
   }
 
   if (collections?.[collectionSlug]?.enabled) {
-    server.tool(
+    server.registerTool(
       `find${collectionSlug.charAt(0).toUpperCase() + toCamelCase(collectionSlug).slice(1)}`,
-      `${collections?.[collectionSlug]?.description || toolSchemas.findResources.description.trim()}`,
-      toolSchemas.findResources.parameters.shape,
+      {
+        description: `${collections?.[collectionSlug]?.description || toolSchemas.findResources.description.trim()}`,
+        inputSchema: toolSchemas.findResources.parameters.shape,
+      },
       async ({ id, depth, draft, fallbackLocale, limit, locale, page, select, sort, where }) => {
         return await tool(
           id,
diff --git a/packages/plugin-mcp/src/mcp/tools/resource/update.ts b/packages/plugin-mcp/src/mcp/tools/resource/update.ts
@@ -335,10 +335,12 @@ ${JSON.stringify(errors, null, 2)}
         .describe('JSON string for where clause to update multiple documents'),
     })
 
-    server.tool(
+    server.registerTool(
       `update${collectionSlug.charAt(0).toUpperCase() + toCamelCase(collectionSlug).slice(1)}`,
-      `${collections?.[collectionSlug]?.description || toolSchemas.updateResource.description.trim()}`,
-      updateResourceSchema.shape,
+      {
+        description: `${collections?.[collectionSlug]?.description || toolSchemas.updateResource.description.trim()}`,
+        inputSchema: updateResourceSchema.shape,
+      },
       async (params: Record<string, unknown>) => {
         const {
           id,
diff --git a/packages/plugin-mcp/src/types.ts b/packages/plugin-mcp/src/types.ts
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/test/plugin-mcp/config.ts b/test/plugin-mcp/config.ts
diff --git a/test/plugin-mcp/int.spec.ts b/test/plugin-mcp/int.spec.ts
