feat(plugin-mcp): adds custom auth config (#14538)

- Adds `overrideAuth` to the MCP Plugin.
- Adds `MCPAccessSettings` as an exported type from the mcpPlugin

```ts
import { type MCPAccessSettings, mcpPlugin } from '@payloadcms/plugin-mcp'

// ... other config

plugins: [
  mcpPlugin({

    // ... other plugin config

    overrideAuth: (req) => {
      const { payload } = req
    
      payload.logger.info('[Override MCP auth]:')
    
      return {
        posts: {
          find: true,
        },
        products: {
          find: true,
          update: true,
        },
      } as MCPAccessSettings
    },
  })
]
```

### Custom Auth Behaviors

The bypassed system uses an API Key that contains `MCPAccessSettings`
information. The `overrideAuth` function will bypass the API Key system
and use your function when authorizing requests.

This means that your function must return a valid `MCPAccessSettings`
object to use.

Author: kendelljoseph

packages/payload/src/errors/index.ts

@@ -20,6 +20,7 @@ export { MissingFile } from './MissingFile.js'
 export { NotFound } from './NotFound.js'
 export { QueryError } from './QueryError.js'
 export { ReservedFieldName } from './ReservedFieldName.js'
+export { UnauthorizedError } from './UnauthorizedError.js'
 export { UnverifiedEmail } from './UnverifiedEmail.js'
 export { ValidationError, ValidationErrorName } from './ValidationError.js'
 export type { ValidationFieldError } from './ValidationError.js'

packages/payload/src/index.ts

@@ -1431,6 +1431,7 @@ export {
   MissingFile,
   NotFound,
   QueryError,
+  UnauthorizedError,
   UnverifiedEmail,
   ValidationError,
   ValidationErrorName,

packages/plugin-mcp/src/collections/createApiKeysCollection.ts

@@ -31,6 +31,7 @@ const addEnabledCollectionTools = (collections: PluginMCPServerConfig['collectio
   return enabledCollectionSlugs.map((enabledCollectionSlug) => ({
     type: 'collapsible' as const,
     admin: {
+      description: `Manage client access to ${enabledCollectionSlug}`,
       position: 'sidebar' as const,
     },
     fields: [
@@ -169,6 +170,8 @@ export const createAPIKeysCollection = (
   return {
     slug: 'payload-mcp-api-keys',
     admin: {
+      description:
+        'API keys control which collections, resources, tools, and prompts MCP clients can access',
       group: 'MCP',
       useAsTitle: 'label',
     },
@@ -208,6 +211,7 @@ export const createAPIKeysCollection = (
             {
               type: 'collapsible' as const,
               admin: {
+                description: 'Manage client access to tools',
                 position: 'sidebar' as const,
               },
               fields: [
@@ -228,6 +232,7 @@ export const createAPIKeysCollection = (
             {
               type: 'collapsible' as const,
               admin: {
+                description: 'Manage client access to resources',
                 position: 'sidebar' as const,
               },
               fields: [
@@ -248,6 +253,7 @@ export const createAPIKeysCollection = (
             {
               type: 'collapsible' as const,
               admin: {
+                description: 'Manage client access to prompts',
                 position: 'sidebar' as const,
               },
               fields: [
@@ -273,6 +279,7 @@ export const createAPIKeysCollection = (
             {
               type: 'collapsible' as const,
               admin: {
+                description: 'Manage client access to experimental tools',
                 position: 'sidebar' as const,
               },
               fields: [

packages/plugin-mcp/src/endpoints/mcp.ts

@@ -1,5 +1,5 @@
 import crypto from 'crypto'
-import { APIError, type PayloadHandler, type Where } from 'payload'
+import { type PayloadHandler, UnauthorizedError, type Where } from 'payload'
 
 import type { MCPAccessSettings, PluginMCPServerConfig } from '../types.js'
 
@@ -13,45 +13,55 @@ export const initializeMCPHandler = (pluginOptions: PluginMCPServerConfig) => {
     const MCPHandlerOptions = MCPOptions.handlerOptions || {}
     const useVerboseLogs = MCPHandlerOptions.verboseLogs ?? false
 
-    const apiKey = req.headers.get('Authorization')?.startsWith('Bearer ')
-      ? req.headers.get('Authorization')?.replace('Bearer ', '').trim()
-      : null
+    const getDefaultMcpAccessSettings = async (overrideApiKey?: null | string) => {
+      const apiKey =
+        (overrideApiKey ?? req.headers.get('Authorization')?.startsWith('Bearer '))
+          ? req.headers.get('Authorization')?.replace('Bearer ', '').trim()
+          : null
 
-    if (apiKey === null) {
-      throw new APIError('API Key is required', 401)
-    }
+      if (apiKey === null) {
+        throw new UnauthorizedError()
+      }
 
-    const sha256APIKeyIndex = crypto
-      .createHmac('sha256', payload.secret)
-      .update(apiKey || '')
-      .digest('hex')
+      const sha256APIKeyIndex = crypto
+        .createHmac('sha256', payload.secret)
+        .update(apiKey || '')
+        .digest('hex')
 
-    const apiKeyConstraints = [
-      {
-        apiKeyIndex: {
-          equals: sha256APIKeyIndex,
+      const apiKeyConstraints = [
+        {
+          apiKeyIndex: {
+            equals: sha256APIKeyIndex,
+          },
         },
-      },
-    ]
-    const where: Where = {
-      or: apiKeyConstraints,
-    }
+      ]
 
-    const { docs } = await payload.find({
-      collection: 'payload-mcp-api-keys',
-      where,
-    })
+      const where: Where = {
+        or: apiKeyConstraints,
+      }
 
-    if (docs.length === 0) {
-      throw new APIError('API Key is invalid', 401)
-    }
+      const { docs } = await payload.find({
+        collection: 'payload-mcp-api-keys',
+        limit: 1,
+        pagination: false,
+        where,
+      })
 
-    const mcpAccessSettings = docs[0] as MCPAccessSettings
+      if (docs.length === 0) {
+        throw new UnauthorizedError()
+      }
 
-    if (useVerboseLogs) {
-      payload.logger.info('[payload-mcp] API Key is valid')
+      if (useVerboseLogs) {
+        payload.logger.info('[payload-mcp] API Key is valid')
+      }
+
+      return docs[0] as MCPAccessSettings
     }
 
+    const mcpAccessSettings = pluginOptions.overrideAuth
+      ? await pluginOptions.overrideAuth(req, getDefaultMcpAccessSettings)
+      : await getDefaultMcpAccessSettings()
+
     const handler = getMCPHandler(pluginOptions, mcpAccessSettings, req)
     const request = createRequestFromPayloadRequest(req)
     return await handler(request)

packages/plugin-mcp/src/index.ts

@@ -1,10 +1,11 @@
 import type { Config } from 'payload'
 
-import type { PluginMCPServerConfig } from './types.js'
+import type { MCPAccessSettings, PluginMCPServerConfig } from './types.js'
 
 import { createAPIKeysCollection } from './collections/createApiKeysCollection.js'
 import { initializeMCPHandler } from './endpoints/mcp.js'
 
+export type { MCPAccessSettings }
 /**
  * The MCP Plugin for Payload. This plugin allows you to add MCP capabilities to your Payload project.
  *

packages/plugin-mcp/src/mcp/createRequest.ts

@@ -1,8 +1,8 @@
-import { APIError, type PayloadRequest } from 'payload'
+import { AuthenticationError, type PayloadRequest } from 'payload'
 
 export const createRequestFromPayloadRequest = (req: PayloadRequest) => {
   if (!req.url) {
-    throw new APIError('Request URL is required', 500)
+    throw new AuthenticationError()
   }
   return new Request(req.url, {
     body: req.body,

packages/plugin-mcp/src/mcp/getMcpHandler.ts

@@ -16,6 +16,9 @@ import { findResourceTool } from './tools/resource/find.js'
 import { updateResourceTool } from './tools/resource/update.js'
 
 // Experimental Tools
+/**
+ * @experimental This tools are experimental and may change or be removed in the future.
+ */
 import { authTool } from './tools/auth/auth.js'
 import { forgotPasswordTool } from './tools/auth/forgotPassword.js'
 import { loginTool } from './tools/auth/login.js'
@@ -108,10 +111,10 @@ export const getMCPHandler = (
             const toolCapabilities = mcpAccessSettings?.[
               `${toCamelCase(enabledCollectionSlug)}`
             ] as Record<string, unknown>
-            const allowCreate: boolean | undefined = toolCapabilities['create'] as boolean
-            const allowUpdate: boolean | undefined = toolCapabilities['update'] as boolean
-            const allowFind: boolean | undefined = toolCapabilities['find'] as boolean
-            const allowDelete: boolean | undefined = toolCapabilities['delete'] as boolean
+            const allowCreate: boolean | undefined = toolCapabilities?.create as boolean
+            const allowUpdate: boolean | undefined = toolCapabilities?.update as boolean
+            const allowFind: boolean | undefined = toolCapabilities?.find as boolean
+            const allowDelete: boolean | undefined = toolCapabilities?.delete as boolean
 
             if (allowCreate) {
               registerTool(
@@ -194,7 +197,7 @@ export const getMCPHandler = (
         // Custom tools
         customMCPTools.forEach((tool) => {
           const camelCasedToolName = toCamelCase(tool.name)
-          const isToolEnabled = mcpAccessSettings['payload-mcp-tool']?.[camelCasedToolName] ?? true
+          const isToolEnabled = mcpAccessSettings['payload-mcp-tool']?.[camelCasedToolName] ?? false
 
           registerTool(
             isToolEnabled,
@@ -209,7 +212,7 @@ export const getMCPHandler = (
         customMCPPrompts.forEach((prompt) => {
           const camelCasedPromptName = toCamelCase(prompt.name)
           const isPromptEnabled =
-            mcpAccessSettings['payload-mcp-prompt']?.[camelCasedPromptName] ?? true
+            mcpAccessSettings['payload-mcp-prompt']?.[camelCasedPromptName] ?? false
 
           if (isPromptEnabled) {
             server.registerPrompt(
@@ -233,7 +236,7 @@ export const getMCPHandler = (
         customMCPResources.forEach((resource) => {
           const camelCasedResourceName = toCamelCase(resource.name)
           const isResourceEnabled =
-            mcpAccessSettings['payload-mcp-resource']?.[camelCasedResourceName] ?? true
+            mcpAccessSettings['payload-mcp-resource']?.[camelCasedResourceName] ?? false
 
           if (isResourceEnabled) {
             server.registerResource(

packages/plugin-mcp/src/types.ts

@@ -215,8 +215,26 @@ export type PluginMCPServerConfig = {
       parameters: z.ZodRawShape
     }[]
   }
+
+  /**
+   * Override the API key collection.
+   * This allows you to add fields to the API key collection or modify the collection in any way you want.
+   * @param collection - The API key collection.
+   * @returns The modified API key collection.
+   */
   overrideApiKeyCollection?: (collection: CollectionConfig) => CollectionConfig
 
+  /**
+   * Override the authentication method.
+   * This allows you to use a custom authentication method instead of the default API key authentication.
+   * @param req - The request object.
+   * @returns The MCP access settings.
+   */
+  overrideAuth?: (
+    req: PayloadRequest,
+    getDefaultMcpAccessSettings: (overrideApiKey?: null | string) => Promise<MCPAccessSettings>,
+  ) => MCPAccessSettings | Promise<MCPAccessSettings>
+
   /**
    * Set the users collection that API keys should be associated with.
    */

test/plugin-mcp/config.ts

@@ -1,5 +1,5 @@
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { mcpPlugin } from '@payloadcms/plugin-mcp'
+import { type MCPAccessSettings, mcpPlugin } from '@payloadcms/plugin-mcp'
 import path from 'path'
 import { fileURLToPath } from 'url'
 import { z } from 'zod'
@@ -24,6 +24,37 @@ export default buildConfigWithDefaults({
   onInit: seed,
   plugins: [
     mcpPlugin({
+      /**
+       * Override the authentication method.
+       * This allows you to use a custom authentication method instead of the default API key authentication.
+       * @param req - The request object.
+       * @returns The MCP access settings.
+       */
+      // overrideAuth: (req) => {
+      //   const { payload } = req
+
+      //   payload.logger.info('[Override MCP auth]:')
+
+      //   return {
+      //     posts: {
+      //       find: true,
+      //     },
+      //     products: {
+      //       find: true,
+      //       update: true,
+      //     },
+      //     'payload-mcp-tool': {
+      //       diceRoll: true,
+      //     },
+      //     'payload-mcp-prompt': {
+      //       echo: true,
+      //     },
+      //     'payload-mcp-resource': {
+      //       data: true,
+      //       dataByID: true,
+      //     },
+      //   } as MCPAccessSettings
+      // },
       overrideApiKeyCollection: (collection) => {
         collection.fields.push({
           name: 'override',

test/plugin-mcp/int.spec.ts

@@ -139,6 +139,24 @@ describe('@payloadcms/plugin-mcp', () => {
     expect(data.error.message).toBe('Method not allowed.')
   })
 
+  it('should not allow POST /api/mcp with unauthorized API key', async () => {
+    const apiKey = await getApiKey()
+    const response = await restClient.POST('/mcp', {
+      headers: {
+        Authorization: `Bearer fake${apiKey}key`,
+        Accept: 'application/json, text/event-stream',
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({}),
+    })
+
+    const json: any = await response.json()
+
+    expect(response.status).toBe(401)
+    expect(json?.errors).toBeDefined()
+    expect(json.errors[0].message).toBe('Unauthorized, you must be logged in to make this request.')
+  })
+
   it('should ping', async () => {
     const apiKey = await getApiKey()
     const response = await restClient.POST('/mcp', {