feat(plugin-mcp): allow external plugins to extend mcp plugin (#16245)

AlessioGr · web-flow · commit ac4fc31a2012 · 2026-04-14T17:46:05.000Z
Plugins can now extend plugin-mcp (e.g. inject custom MCP tools). A
plugin finds plugin-mcp by slug via `config.plugins`, accesses its
options, and pushes tools directly into `options.mcp.tools`. Because
plugin-mcp uses a high priority (runs last), the injected tools are
available when it builds the MCP server.

Also exports `MCPPluginConfig` type so external plugins can type the
options object when injecting tools. Since it wasn't exported before, I
took the opportunity to rename `PluginMCPServerConfig` =&gt;
`MCPPluginConfig`. This is simpler and more consistent with type from
our other plugins
diff --git a/packages/plugin-mcp/src/collections/createApiKeysCollection.ts b/packages/plugin-mcp/src/collections/createApiKeysCollection.ts
@@ -1,16 +1,16 @@
 import type { CollectionConfig, CollectionSlug } from 'payload'
 
-import type { PluginMCPServerConfig } from '../types.js'
+import type { MCPPluginConfig } from '../types.js'
 
 import { toCamelCase } from '../utils/camelCase.js'
 import { createApiKeyFields } from '../utils/createApiKeyFields.js'
 
 export const createAPIKeysCollection = (
-  collections: PluginMCPServerConfig['collections'],
-  globals: PluginMCPServerConfig['globals'],
+  collections: MCPPluginConfig['collections'],
+  globals: MCPPluginConfig['globals'],
   customTools: Array<{ description: string; name: string }> = [],
-  experimentalTools: NonNullable<PluginMCPServerConfig['experimental']>['tools'] = {},
-  pluginOptions: PluginMCPServerConfig,
+  experimentalTools: NonNullable<MCPPluginConfig['experimental']>['tools'] = {},
+  pluginOptions: MCPPluginConfig,
 ): CollectionConfig => {
   const customToolsFields = customTools.map((tool) => {
     const camelCasedName = toCamelCase(tool.name)
diff --git a/packages/plugin-mcp/src/endpoints/mcp.ts b/packages/plugin-mcp/src/endpoints/mcp.ts
@@ -1,12 +1,12 @@
 import crypto from 'crypto'
 import { type PayloadHandler, type TypedUser, UnauthorizedError, type Where } from 'payload'
 
-import type { MCPAccessSettings, PluginMCPServerConfig } from '../types.js'
+import type { MCPAccessSettings, MCPPluginConfig } from '../types.js'
 
 import { createRequestFromPayloadRequest } from '../mcp/createRequest.js'
 import { getMCPHandler } from '../mcp/getMcpHandler.js'
 
-export const initializeMCPHandler = (pluginOptions: PluginMCPServerConfig) => {
+export const initializeMCPHandler = (pluginOptions: MCPPluginConfig) => {
   const mcpHandler: PayloadHandler = async (req) => {
     const { payload } = req
     const MCPOptions = pluginOptions.mcp || {}
diff --git a/packages/plugin-mcp/src/index.ts b/packages/plugin-mcp/src/index.ts
@@ -1,6 +1,6 @@
-import type { Config } from 'payload'
+import { definePlugin } from 'payload'
 
-import type { MCPAccessSettings, PluginMCPServerConfig } from './types.js'
+import type { MCPAccessSettings, MCPPluginConfig } from './types.js'
 
 import { createAPIKeysCollection } from './collections/createApiKeysCollection.js'
 import { initializeMCPHandler } from './endpoints/mcp.js'
@@ -9,19 +9,24 @@ declare module 'payload' {
   export interface PayloadRequest {
     payloadAPI: 'GraphQL' | 'local' | 'MCP' | 'REST'
   }
+  interface RegisteredPlugins {
+    '@payloadcms/plugin-mcp': MCPPluginConfig
+  }
 }
 
 import { defaults } from './defaults.js'
 
-export type { MCPAccessSettings }
+export type { MCPAccessSettings, MCPPluginConfig }
+
 /**
  * The MCP Plugin for Payload. This plugin allows you to add MCP capabilities to your Payload project.
  *
  * @param pluginOptions - The options for the MCP plugin.
  */
-export const mcpPlugin =
-  (pluginOptions: PluginMCPServerConfig) =>
-  (config: Config): Config => {
+export const mcpPlugin = definePlugin<MCPPluginConfig>({
+  slug: '@payloadcms/plugin-mcp',
+  order: 10,
+  plugin: ({ config, plugins: _plugins, ...pluginOptions }) => {
     if (!config.collections) {
       config.collections = []
     }
@@ -104,4 +109,5 @@ export const mcpPlugin =
     })
 
     return config
-  }
+  },
+})
diff --git a/packages/plugin-mcp/src/mcp/getMcpHandler.ts b/packages/plugin-mcp/src/mcp/getMcpHandler.ts
@@ -4,7 +4,7 @@ import { createMcpHandler } from 'mcp-handler'
 import { join } from 'path'
 import { APIError, configToJSONSchema, type PayloadRequest, type TypedUser } from 'payload'
 
-import type { MCPAccessSettings, PluginMCPServerConfig } from '../types.js'
+import type { MCPAccessSettings, MCPPluginConfig } from '../types.js'
 
 import { toCamelCase } from '../utils/camelCase.js'
 import { getEnabledSlugs } from '../utils/getEnabledSlugs.js'
@@ -44,7 +44,7 @@ import { runJobTool } from './tools/job/run.js'
 import { updateJobTool } from './tools/job/update.js'
 
 export const getMCPHandler = (
-  pluginOptions: PluginMCPServerConfig,
+  pluginOptions: MCPPluginConfig,
   mcpAccessSettings: MCPAccessSettings,
   req: PayloadRequest,
 ) => {
@@ -63,15 +63,15 @@ export const getMCPHandler = (
   }
 
   const payloadToolHandler = (
-    handler: NonNullable<NonNullable<PluginMCPServerConfig['mcp']>['tools']>[number]['handler'],
+    handler: NonNullable<NonNullable<MCPPluginConfig['mcp']>['tools']>[number]['handler'],
   ) => wrapHandler(handler)
 
   const payloadPromptHandler = (
-    handler: NonNullable<NonNullable<PluginMCPServerConfig['mcp']>['prompts']>[number]['handler'],
+    handler: NonNullable<NonNullable<MCPPluginConfig['mcp']>['prompts']>[number]['handler'],
   ) => wrapHandler(handler)
 
   const payloadResourceHandler = (
-    handler: NonNullable<NonNullable<PluginMCPServerConfig['mcp']>['resources']>[number]['handler'],
+    handler: NonNullable<NonNullable<MCPPluginConfig['mcp']>['resources']>[number]['handler'],
   ) => wrapHandler(handler)
 
   // User
@@ -88,7 +88,7 @@ export const getMCPHandler = (
 
   // Experimental MCP Tool Requirements
   const isDevelopment = process.env.NODE_ENV === 'development'
-  const experimentalTools: NonNullable<PluginMCPServerConfig['experimental']>['tools'] =
+  const experimentalTools: NonNullable<MCPPluginConfig['experimental']>['tools'] =
     pluginOptions?.experimental?.tools || {}
   const collectionsPluginConfig = pluginOptions.collections || {}
   const globalsPluginConfig = pluginOptions.globals || {}
diff --git a/packages/plugin-mcp/src/mcp/tools/global/find.ts b/packages/plugin-mcp/src/mcp/tools/global/find.ts
@@ -1,7 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import type { PayloadRequest, SelectType, TypedUser } from 'payload'
 
-import type { PluginMCPServerConfig } from '../../../types.js'
+import type { MCPPluginConfig } from '../../../types.js'
 
 import { toCamelCase } from '../../../utils/camelCase.js'
 import { toolSchemas } from '../schemas.js'
@@ -12,7 +12,7 @@ export const findGlobalTool = (
   user: TypedUser,
   verboseLogs: boolean,
   globalSlug: string,
-  globals: PluginMCPServerConfig['globals'],
+  globals: MCPPluginConfig['globals'],
 ) => {
   const tool = async (
     depth: number = 0,
diff --git a/packages/plugin-mcp/src/mcp/tools/global/update.ts b/packages/plugin-mcp/src/mcp/tools/global/update.ts
@@ -4,7 +4,7 @@ import type { PayloadRequest, SelectType, TypedUser } from 'payload'
 
 import { z } from 'zod'
 
-import type { PluginMCPServerConfig } from '../../../types.js'
+import type { MCPPluginConfig } from '../../../types.js'
 
 import { toCamelCase } from '../../../utils/camelCase.js'
 import {
@@ -20,7 +20,7 @@ export const updateGlobalTool = (
   user: TypedUser,
   verboseLogs: boolean,
   globalSlug: string,
-  globals: PluginMCPServerConfig['globals'],
+  globals: MCPPluginConfig['globals'],
   schema: JSONSchema4,
 ) => {
   const tool = async (
diff --git a/packages/plugin-mcp/src/mcp/tools/resource/create.ts b/packages/plugin-mcp/src/mcp/tools/resource/create.ts
@@ -4,7 +4,7 @@ import type { PayloadRequest, SelectType, TypedUser } from 'payload'
 
 import { z } from 'zod'
 
-import type { PluginMCPServerConfig } from '../../../types.js'
+import type { MCPPluginConfig } from '../../../types.js'
 
 import { toCamelCase } from '../../../utils/camelCase.js'
 import {
@@ -20,7 +20,7 @@ export const createResourceTool = (
   user: TypedUser,
   verboseLogs: boolean,
   collectionSlug: string,
-  collections: PluginMCPServerConfig['collections'],
+  collections: MCPPluginConfig['collections'],
   schema: JSONSchema4,
 ) => {
   const tool = async (
diff --git a/packages/plugin-mcp/src/mcp/tools/resource/delete.ts b/packages/plugin-mcp/src/mcp/tools/resource/delete.ts
@@ -1,7 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import type { PayloadRequest, TypedUser } from 'payload'
 
-import type { PluginMCPServerConfig } from '../../../types.js'
+import type { MCPPluginConfig } from '../../../types.js'
 
 import { toCamelCase } from '../../../utils/camelCase.js'
 import { toolSchemas } from '../schemas.js'
@@ -12,7 +12,7 @@ export const deleteResourceTool = (
   user: TypedUser,
   verboseLogs: boolean,
   collectionSlug: string,
-  collections: PluginMCPServerConfig['collections'],
+  collections: MCPPluginConfig['collections'],
 ) => {
   const tool = async (
     id?: number | string,
diff --git a/packages/plugin-mcp/src/mcp/tools/resource/find.ts b/packages/plugin-mcp/src/mcp/tools/resource/find.ts
@@ -1,7 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import type { PayloadRequest, SelectType, TypedUser } from 'payload'
 
-import type { PluginMCPServerConfig } from '../../../types.js'
+import type { MCPPluginConfig } from '../../../types.js'
 
 import { toCamelCase } from '../../../utils/camelCase.js'
 import { toolSchemas } from '../schemas.js'
@@ -12,7 +12,7 @@ export const findResourceTool = (
   user: TypedUser,
   verboseLogs: boolean,
   collectionSlug: string,
-  collections: PluginMCPServerConfig['collections'],
+  collections: MCPPluginConfig['collections'],
 ) => {
   const tool = async (
     id?: number | string,
diff --git a/packages/plugin-mcp/src/mcp/tools/resource/update.ts b/packages/plugin-mcp/src/mcp/tools/resource/update.ts
@@ -4,7 +4,7 @@ import type { PayloadRequest, SelectType, TypedUser } from 'payload'
 
 import { z } from 'zod'
 
-import type { PluginMCPServerConfig } from '../../../types.js'
+import type { MCPPluginConfig } from '../../../types.js'
 
 import { toCamelCase } from '../../../utils/camelCase.js'
 import {
@@ -20,7 +20,7 @@ export const updateResourceTool = (
   user: TypedUser,
   verboseLogs: boolean,
   collectionSlug: string,
-  collections: PluginMCPServerConfig['collections'],
+  collections: MCPPluginConfig['collections'],
   schema: JSONSchema4,
 ) => {
   const tool = async (
diff --git a/packages/plugin-mcp/src/types.ts b/packages/plugin-mcp/src/types.ts
@@ -9,7 +9,7 @@ import type { z } from 'zod'
 
 import { type ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
 
-export type PluginMCPServerConfig = {
+export type MCPPluginConfig = {
   /**
    * Set the collections that should be available as resources via MCP.
    */
@@ -425,7 +425,7 @@ export type MCPAccessSettings = {
   user: TypedUser
 } & Record<string, unknown>
 
-export type EntityConfig = PluginMCPServerConfig['collections'] | PluginMCPServerConfig['globals']
+export type EntityConfig = MCPPluginConfig['collections'] | MCPPluginConfig['globals']
 
 export type FieldDefinition = {
   description?: string
diff --git a/test/plugin-mcp/config.ts b/test/plugin-mcp/config.ts
@@ -1,6 +1,7 @@
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { type MCPAccessSettings, mcpPlugin } from '@payloadcms/plugin-mcp'
+import { mcpPlugin } from '@payloadcms/plugin-mcp'
 import path from 'path'
+import { definePlugin } from 'payload'
 import { fileURLToPath } from 'url'
 import { z } from 'zod'
 
@@ -67,6 +68,29 @@ export default buildConfigWithDefaults({
   globals: [SiteSettings],
   onInit: seed,
   plugins: [
+    // Plugin listed BEFORE mcp in the array — injects a tool via slug + options
+    definePlugin({
+      order: 1,
+      slug: 'before-mcp',
+      plugin: ({ config, plugins }) => {
+        const mcp = plugins['@payloadcms/plugin-mcp']
+        if (mcp?.options) {
+          const opts = mcp.options
+          opts.mcp ??= {}
+          opts.mcp.tools ??= []
+          opts.mcp.tools.push({
+            name: 'injectedBefore',
+            description: 'Tool injected by a plugin listed before mcp',
+            handler: () => ({
+              content: [{ type: 'text' as const, text: 'injected-before' }],
+            }),
+            parameters: {},
+          })
+        }
+        return config
+      },
+    })(),
+
     mcpPlugin({
       /**
        * Override the authentication method.
@@ -381,6 +405,28 @@ export default buildConfigWithDefaults({
         },
       },
     }),
+    // Plugin listed AFTER mcp in the array — also injects a tool via slug + options
+    definePlugin({
+      order: 1,
+      slug: 'after-mcp',
+      plugin: ({ config, plugins }) => {
+        const mcp = plugins['@payloadcms/plugin-mcp']
+        if (mcp?.options) {
+          const opts = mcp.options
+          opts.mcp ??= {}
+          opts.mcp.tools ??= []
+          opts.mcp.tools.push({
+            name: 'injectedAfter',
+            description: 'Tool injected by a plugin listed after mcp',
+            handler: () => ({
+              content: [{ type: 'text' as const, text: 'injected-after' }],
+            }),
+            parameters: {},
+          })
+        }
+        return config
+      },
+    })(),
   ],
   typescript: {
     outputFile: path.resolve(dirname, 'payload-types.ts'),
diff --git a/test/plugin-mcp/int.spec.ts b/test/plugin-mcp/int.spec.ts
@@ -298,7 +298,7 @@ describe('@payloadcms/plugin-mcp', () => {
       expect(json.jsonrpc).toBe('2.0')
       expect(json.result).toBeDefined()
       expect(json.result.tools).toBeDefined()
-      expect(json.result.tools).toHaveLength(4)
+      expect(json.result.tools).toHaveLength(6)
       expect(json.result.tools[0].name).toBe('findProducts')
       expect(json.result.tools[0].description).toContain(
         'Find documents in a collection by ID or where clause using Find or FindByID.',
@@ -498,6 +498,31 @@ describe('@payloadcms/plugin-mcp', () => {
       )
     })
 
+    it('should list tools injected by other plugins via slug and options', async () => {
+      const apiKey = await getApiKey()
+      const response = await restClient.POST('/mcp', {
+        body: JSON.stringify({
+          id: 1,
+          jsonrpc: '2.0',
+          method: 'tools/list',
+          params: {},
+        }),
+        headers: {
+          Accept: 'application/json, text/event-stream',
+          Authorization: `Bearer ${apiKey}`,
+          'Content-Type': 'application/json',
+        },
+      })
+
+      const json = await parseStreamResponse(response)
+      const toolNames = json.result.tools.map((t: { name: string }) => t.name)
+
+      // Both plugins inject tools into mcp's options via slug discovery,
+      // regardless of whether they are listed before or after mcp in the plugins array
+      expect(toolNames).toContain('injectedBefore')
+      expect(toolNames).toContain('injectedAfter')
+    })
+
     it('should list resources', async () => {
       const apiKey = await getApiKey()
       const response = await restClient.POST('/mcp', {
