@payloadcms/plugin-mcp 4.0.0-internal.011fd46 → 4.0.0-internal.0b9bec1

package/src/mcp/sanitizeMCPConfig.ts

@@ -17,6 +17,7 @@ import type {
   SanitizedMCPPluginConfig,
 } from '../types.js'
 
+import { defaultAccess } from '../defaultAccess.js'
 import {
   COLLECTION_AUTH_BUILTIN_ENTRIES,
   COLLECTION_AUTH_BUILTINS,
@@ -33,7 +34,6 @@ import {
  *  - Flattens `tools` / `prompts` / `resources` / per-collection / per-global
  *    tool maps into a single `items` array.
  *  - Applies built-in tools for collections and globals, respecting opt-out user overrides.
- *  - Applies the `userCollection` default
  *
  * Called once during plugin init. After that, `plugins['@payloadcms/plugin-mcp']
  * ?.options` holds the sanitized result
@@ -61,7 +61,7 @@ export const sanitizeMCPConfig = ({
       configKey,
       label: tool.annotations?.title ?? configKey,
       mcpName,
-      tool,
+      tool: { ...tool, access: tool.access ?? defaultAccess },
     })
   }
 
@@ -74,7 +74,7 @@ export const sanitizeMCPConfig = ({
       configKey,
       label: tool.annotations?.title ?? configKey,
       mcpName: configKey,
-      tool,
+      tool: { ...tool, access: tool.access ?? defaultAccess },
     })
   }
 
@@ -84,7 +84,7 @@ export const sanitizeMCPConfig = ({
       configKey,
       label: prompt.title ?? configKey,
       mcpName: configKey,
-      prompt,
+      prompt: { ...prompt, access: prompt.access ?? defaultAccess },
     })
   }
 
@@ -94,21 +94,16 @@ export const sanitizeMCPConfig = ({
       configKey,
       label: resource.title ?? configKey,
       mcpName: configKey,
-      resource,
+      resource: { ...resource, access: resource.access ?? defaultAccess },
     })
   }
 
-  // Mirror Payload's own admin.user detection (sanitize.ts) since plugins run first.
-  const firstCollectionWithAuth = config.collections!.find(({ auth }) => Boolean(auth))
-
   return {
     disabled: pluginConfig.disabled,
+    hooks: pluginConfig.hooks,
     items,
     mcp: pluginConfig.mcp,
-    overrideApiKeyCollection: pluginConfig.overrideApiKeyCollection,
-    overrideAuth: pluginConfig.overrideAuth,
-    userCollection:
-      pluginConfig.userCollection ?? config.admin?.user ?? firstCollectionWithAuth?.slug ?? 'users',
+    overrideGetAuthorizedMCP: pluginConfig.overrideGetAuthorizedMCP,
   }
 }
 
@@ -119,14 +114,30 @@ const sanitizeCollectionConfig = ({
   collection: CollectionConfig | SanitizedCollectionConfig
   pluginConfig: MCPPluginConfig
 }): CollectionMCPItem[] => {
-  if (collection.slug === 'payload-mcp-api-keys') {
-    return []
-  }
   const slug = collection.slug
   const collectionPluginConfig = pluginConfig.collections?.[slug]
   const items: CollectionMCPItem[] = []
+  /**
+   * Payload disables duplicate for auth collections by default unless the
+   * collection explicitly opts back in with `disableDuplicate: false`.
+   */
+  const isDuplicateDisabled =
+    collection.disableDuplicate === true ||
+    (Boolean(collection.auth) && collection.disableDuplicate !== false)
 
-  for (const [toolKey, { mcpName, tool }] of COLLECTION_BUILTIN_ENTRIES) {
+  for (const [
+    toolKey,
+    { mcpName, requiresDuplicateEnabled, requiresUpload, requiresVersions, tool },
+  ] of COLLECTION_BUILTIN_ENTRIES) {
+    if (requiresVersions && !collection.versions) {
+      continue
+    }
+    if (requiresDuplicateEnabled && isDuplicateDisabled) {
+      continue
+    }
+    if (requiresUpload && !collection.upload) {
+      continue
+    }
     const matchedConfigEntry = collectionPluginConfig?.tools?.[toolKey]
     if (matchedConfigEntry === false) {
       continue
@@ -141,6 +152,7 @@ const sanitizeCollectionConfig = ({
       mcpName,
       tool: {
         ...tool,
+        access: override?.access ?? tool.access ?? defaultAccess,
         annotations,
         description: override?.description ?? tool.description,
         overrideResponse:
@@ -168,6 +180,7 @@ const sanitizeCollectionConfig = ({
         mcpName,
         tool: {
           ...tool,
+          access: override?.access ?? tool.access ?? defaultAccess,
           annotations,
           description: override?.description ?? tool.description,
           overrideResponse:
@@ -197,7 +210,7 @@ const sanitizeCollectionConfig = ({
       configKey,
       label: customTool.annotations?.title ?? configKey,
       mcpName: configKey,
-      tool: customTool,
+      tool: { ...customTool, access: customTool.access ?? defaultAccess },
     })
   }
 
@@ -215,7 +228,10 @@ const sanitizeGlobalConfig = ({
   const globalPluginConfig = pluginConfig.globals?.[slug]
   const items: GlobalMCPItem[] = []
 
-  for (const [toolKey, { mcpName, tool }] of GLOBAL_BUILTIN_ENTRIES) {
+  for (const [toolKey, { mcpName, requiresVersions, tool }] of GLOBAL_BUILTIN_ENTRIES) {
+    if (requiresVersions && !global.versions) {
+      continue
+    }
     const matchedConfigEntry = globalPluginConfig?.tools?.[toolKey]
     if (matchedConfigEntry === false) {
       continue
@@ -230,6 +246,7 @@ const sanitizeGlobalConfig = ({
       mcpName,
       tool: {
         ...tool,
+        access: override?.access ?? tool.access ?? defaultAccess,
         annotations,
         description: override?.description ?? tool.description,
         overrideResponse:
@@ -256,7 +273,7 @@ const sanitizeGlobalConfig = ({
       globalSlug: slug,
       label: customTool.annotations?.title ?? configKey,
       mcpName: configKey,
-      tool: customTool,
+      tool: { ...customTool, access: customTool.access ?? defaultAccess },
     })
   }
 

package/src/stdio.ts

@@ -1,98 +1,131 @@
-import type { MaybePromise, Plugin, SanitizedConfig } from 'payload'
+import type { Config, Plugin, SanitizedConfig } from 'payload'
 
 /* eslint-disable no-console */
-import { StdioServerTransport } from '@modelcontextprotocol/server'
+import { serveStdio } from '@modelcontextprotocol/server/stdio'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { createLocalReq, getPayload } from 'payload'
-import { findConfig } from 'payload/node'
+import { findConfig, loadEnv } from 'payload/node'
 
-import type { AuthorizedMCP, SanitizedMCPPluginConfig } from './types.js'
+import type { SanitizedMCPPluginConfig } from './types.js'
 
+import { getAuthorizedMCP } from './endpoint/access.js'
 import { buildMcpServer } from './mcp/buildMcpServer.js'
 import { sanitizeMCPConfig } from './mcp/sanitizeMCPConfig.js'
 import { getPluginConfig } from './utils/getPluginConfig.js'
 import { resolveProjectRoot } from './utils/resolveProjectRoot.js'
 
 /**
- * Stdio adapter for the Payload MCP server.
+ * Starts Payload's MCP server over stdin and stdout.
  *
- * Do not use in production. There's no auth; whoever can spawn the process gets
- * full access to your local data.
+ * Set `PAYLOAD_MCP_AUTHORIZATION` to authenticate. In development,
+ * `PAYLOAD_MCP_OVERRIDE_ACCESS=true` skips access checks.
  */
 export const runMcpStdio = async (): Promise<void> => {
-  /**
-   * If MCP clients spawn stdio servers from an arbitrary working directory,
-   * Payload's cwd-anchored `findConfig()` can't locate the project on
-   * its own. This module always lives inside the project's `node_modules`, so
-   * we derive the project root from its own path and `chdir` into it.
-   *
-   * An absolute `PAYLOAD_CONFIG_PATH` still overrides everything; unusual
-   * layouts (e.g. a monorepo where the package is hoisted above the app) can
-   * fall back to it. See the implementation of findConfig for details.
-   */
+  // MCP clients may start this command from another folder. Move to the Payload
+  // project so findConfig() can find the config.
   const projectRoot = resolveProjectRoot(fileURLToPath(import.meta.url))
   if (projectRoot) {
     process.chdir(projectRoot)
   }
 
+  loadEnv()
   const configPath = findConfig()
   const configModule = await import(pathToFileURL(configPath).toString())
-  const config = (await (configModule.default ?? configModule)) as MaybePromise<SanitizedConfig>
-
-  const payload = await getPayload({ config })
+  const config = (await (configModule.default ?? configModule)) as SanitizedConfig
 
   /**
-   * If the user added `mcpPlugin({...})` to their `plugins` array, read the
-   * sanitized config they registered. Otherwise fall back to the defaults. That way,
-   * the mcp works on any project that has `@payloadcms/plugin-mcp` installed,
-   * even if the plugin is not added to the plugins array.
+   * stdout is only for MCP messages. The spec says the server must not write
+   * logs there and may write them to stderr instead.
+   *
+   * The 2.0 client library recovers from stray stdout logs, but that behavior is not
+   * guaranteed. Move Payload logs to stderr so Payload does not add invalid data
+   * to stdout. Keep options from configurable loggers. Replace pre-built loggers
+   * because their output cannot be redirected.
+   *
+   * @see https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#stdio
    */
+  const loggerConfig: { logger?: Config['logger'] } = config
+  if (
+    loggerConfig.logger &&
+    typeof loggerConfig.logger === 'object' &&
+    'options' in loggerConfig.logger
+  ) {
+    loggerConfig.logger.destination = process.stderr
+  } else {
+    loggerConfig.logger = { destination: process.stderr, options: {} }
+  }
+
+  const payload = await getPayload({ config, cron: false, disableOnInit: true })
+
   let pluginConfig: SanitizedMCPPluginConfig
   try {
     pluginConfig = getPluginConfig({ config: payload.config })
   } catch {
+    // The command also works when mcpPlugin() is not in the Payload config.
     pluginConfig = sanitizeMCPConfig({ config: payload.config, pluginConfig: {} })
 
-    const fakePluginFn: Plugin = (config) => config
-    fakePluginFn.slug = '@payloadcms/plugin-mcp'
-    // @ts-expect-error
-    fakePluginFn.sanitizedOptions = pluginConfig
+    const fallbackPlugin: Plugin = (config) => config
+    Object.assign(fallbackPlugin, {
+      slug: '@payloadcms/plugin-mcp',
+      sanitizedOptions: pluginConfig,
+    })
+    payload.config.plugins ??= []
+    payload.config.plugins.push(fallbackPlugin)
+  }
+
+  const overrideAccessEnv = process.env.PAYLOAD_MCP_OVERRIDE_ACCESS
+  let overrideAccess = false
+
+  if (overrideAccessEnv === 'true') {
+    overrideAccess = true
+  } else if (overrideAccessEnv && overrideAccessEnv !== 'false') {
+    throw new Error('PAYLOAD_MCP_OVERRIDE_ACCESS must be "true" or "false".')
+  }
 
-    // Push to payload config, to ensure consecutive calls to `getPluginConfig()` work
-    ;(payload.config.plugins ??= []).push(fakePluginFn)
+  if (overrideAccess && process.env.NODE_ENV !== 'development') {
+    throw new Error('PAYLOAD_MCP_OVERRIDE_ACCESS is only available in development.')
   }
 
-  const authorizedMCP: AuthorizedMCP = {
-    items: pluginConfig.items,
-    overrideAccess: true,
-    user: null,
+  const headers = new Headers()
+  if (process.env.PAYLOAD_MCP_AUTHORIZATION) {
+    headers.set('Authorization', process.env.PAYLOAD_MCP_AUTHORIZATION)
   }
 
-  const req = await createLocalReq({}, payload)
+  const req = await createLocalReq({ req: { headers } }, payload)
   req.payloadAPI = 'MCP' as const
+  const authorizedMCP = await getAuthorizedMCP({ overrideAccess, req })
 
-  const server = buildMcpServer({ authorizedMCP, pluginConfig, req })
+  const stdioServer = serveStdio(() => buildMcpServer({ authorizedMCP, pluginConfig, req }), {
+    onerror: (err) => {
+      // MCP messages use stdout, so write SDK errors to stderr.
+      console.error('[payload-mcp] error serving MCP over stdio:', err)
+    },
+  })
 
-  const transport = new StdioServerTransport()
-  await server.connect(transport)
+  // Close the MCP server and Payload when the client disconnects or the process stops.
+  let isShuttingDown = false
+  const shutdown = async () => {
+    if (isShuttingDown) {
+      return
+    }
+    isShuttingDown = true
 
-  // Process now lives until stdin closes. Wire graceful shutdown so DB
-  // connections (and any other Payload-managed resources) get released.
-  const shutdown = async (code = 0) => {
     try {
-      await server.close()
+      await stdioServer.close()
     } catch (err) {
       console.error('[payload-mcp] error closing server:', err)
     }
+
     try {
       await payload.destroy()
     } catch (err) {
       console.error('[payload-mcp] error destroying payload:', err)
     }
-    process.exit(code)
+
+    process.exit(0)
   }
 
-  process.on('SIGINT', () => void shutdown(0))
-  process.on('SIGTERM', () => void shutdown(0))
-  process.stdin.on('close', () => void shutdown(0))
+  process.once('SIGINT', () => void shutdown())
+  process.once('SIGTERM', () => void shutdown())
+  process.stdin.once('close', () => void shutdown())
 }

package/src/types.ts

@@ -10,15 +10,14 @@ import type {
 } from '@modelcontextprotocol/server'
 import type {
   AuthCollectionSlug,
-  CollectionConfig,
   CollectionSlug,
-  DefaultDocumentIDType,
   GlobalSlug,
   MaybePromise,
   PayloadRequest,
-  TypedUser,
+  SanitizedPermissions,
 } from 'payload'
 
+import type { GetAuthorizedMCPArgs } from './endpoint/access.js'
 import type {
   MCPCollectionAuthToolName,
   MCPCollectionBuiltinName,
@@ -32,31 +31,11 @@ export type { JsonSchemaType, StandardSchemaWithJSON, ToolAnnotations }
 
 /**
  * What a tool's `input` (or a prompt's `argsSchema`) can be — either a raw
- * JSON Schema literal, or a Standard Schema instance (Zod, Valibot, …).
+ * JSON Schema 2020-12 literal, or a Standard Schema instance (Zod, Valibot, …).
+ * Raw schemas may omit `$schema`; when present it must declare the 2020-12 dialect.
  */
 export type ToolInputSchema = JsonSchemaType | StandardSchemaWithJSON
 
-/**
- * Serializable mirror of `SanitizedMCPPluginConfig` for client components —
- * the full sanitized config carries functions (tool handlers, etc.) that can't
- * cross the server→client boundary. Built by `sanitizeClientPluginConfig` and
- * passed to the `AccessField` component via `clientProps`.
- *
- * @internal
- */
-export type ClientMCPPluginConfig = {
-  items: Array<{
-    collectionSlug?: string
-    configKey: string
-    description?: string
-    globalSlug?: string
-    /** Admin-UI bucket for collection/global tools: built-in CRUD, auth, or custom. */
-    group?: 'auth' | 'custom' | 'operations'
-    label: string
-    type: 'collectionTool' | 'globalTool' | 'prompt' | 'resource' | 'tool'
-  }>
-}
-
 export type MCPToolResponse = {
   content: ContentBlock[]
   /**
@@ -73,6 +52,13 @@ export type MCPResponseOverride = (
   req: PayloadRequest,
 ) => MCPToolResponse
 
+export type MCPAfterToolCallHook = (args: {
+  input: unknown
+  req: PayloadRequest
+  response: MCPToolResponse
+  toolName: string
+}) => MaybePromise<MCPToolResponse>
+
 /**
  * The handler's `input` type. A specific Standard Schema (Zod, Valibot, …) gets
  * its inferred output; anything else falls back to `Record<string, unknown>`.
@@ -83,6 +69,19 @@ export type TypedInput<TSchema> = TSchema extends StandardSchemaWithJSON
     : StandardSchemaWithJSON.InferOutput<TSchema>
   : Record<string, unknown>
 
+export type MCPAccessArgs = {
+  permissions?: SanitizedPermissions
+  req: PayloadRequest
+}
+
+export type CollectionMCPAccessArgs = {
+  collectionSlug: CollectionSlug
+} & MCPAccessArgs
+
+export type GlobalMCPAccessArgs = {
+  globalSlug: GlobalSlug
+} & MCPAccessArgs
+
 export type ToolHandlerArgs<TSchema = undefined> = {
   authorizedMCP: AuthorizedMCP
   input: TypedInput<TSchema>
@@ -99,6 +98,12 @@ export type GlobalToolHandlerArgs<TSchema = undefined> = {
 } & ToolHandlerArgs<TSchema>
 
 export type Tool<TSchema extends ToolInputSchema | undefined = ToolInputSchema | undefined> = {
+  /**
+   * Runs while authorizing each MCP request, before the tool is advertised or called. Return
+   * `false` to make the tool unavailable for that request. This is skipped when `overrideAccess`
+   * is enabled.
+   */
+  access?: (args: MCPAccessArgs) => MaybePromise<boolean>
   annotations?: ToolAnnotations
   description: string
   handler: (args: ToolHandlerArgs<TSchema>) => MaybePromise<MCPToolResponse>
@@ -112,12 +117,26 @@ export type Tool<TSchema extends ToolInputSchema | undefined = ToolInputSchema |
 export type CollectionTool<
   TSchema extends ToolInputSchema | undefined = ToolInputSchema | undefined,
 > = {
+  /**
+   * Runs while authorizing each MCP request for this collection. Return `false` to reject calls
+   * to this tool for the collection. The shared tool is not advertised when no collections allow
+   * it, but can remain advertised when it is available for another collection. This is skipped
+   * when `overrideAccess` is enabled.
+   */
+  access?: (args: CollectionMCPAccessArgs) => MaybePromise<boolean>
   handler: (args: CollectionToolHandlerArgs<TSchema>) => MaybePromise<MCPToolResponse>
   input?: TSchema
 } & Pick<Tool, 'annotations' | 'description' | 'overrideResponse'>
 
 export type GlobalTool<TSchema extends ToolInputSchema | undefined = ToolInputSchema | undefined> =
   {
+    /**
+     * Runs while authorizing each MCP request for this global. Return `false` to reject calls to
+     * this tool for the global. The shared tool is not advertised when no globals allow it, but
+     * can remain advertised when it is available for another global. This is skipped when
+     * `overrideAccess` is enabled.
+     */
+    access?: (args: GlobalMCPAccessArgs) => MaybePromise<boolean>
     handler: (args: GlobalToolHandlerArgs<TSchema>) => MaybePromise<MCPToolResponse>
     input?: TSchema
   } & Pick<Tool, 'annotations' | 'description' | 'overrideResponse'>
@@ -127,7 +146,24 @@ export type GlobalTool<TSchema extends ToolInputSchema | undefined = ToolInputSc
  * `handler?: never` prevents a full `CollectionTool`/`GlobalTool` (which has a
  * required handler) from being silently accepted at a built-in key slot.
  */
-export type MCPBuiltInToolOverride = {
+export type MCPBuiltInCollectionToolOverride = {
+  /**
+   * Replaces the built-in tool's access check. Return `false` to make the tool unavailable for
+   * this collection. This is skipped when `overrideAccess` is enabled.
+   */
+  access?: (args: CollectionMCPAccessArgs) => MaybePromise<boolean>
+  annotations?: ToolAnnotations
+  description?: string
+  handler?: never
+  overrideResponse?: MCPResponseOverride
+}
+
+export type MCPBuiltInGlobalToolOverride = {
+  /**
+   * Replaces the built-in tool's access check. Return `false` to make the tool unavailable for
+   * this global. This is skipped when `overrideAccess` is enabled.
+   */
+  access?: (args: GlobalMCPAccessArgs) => MaybePromise<boolean>
   annotations?: ToolAnnotations
   description?: string
   handler?: never
@@ -142,13 +178,13 @@ export type MCPBuiltInToolOverride = {
 export type MCPTopLevelToolEntry = Tool
 
 export type MCPCollectionToolsMap = {
-  [customToolName: string]: boolean | CollectionTool | MCPBuiltInToolOverride | undefined
+  [customToolName: string]: boolean | CollectionTool | MCPBuiltInCollectionToolOverride | undefined
 } & {
-  [K in MCPCollectionBuiltinName]?: false | MCPBuiltInToolOverride
+  [K in MCPCollectionBuiltinName]?: false | MCPBuiltInCollectionToolOverride
 }
 
 export type MCPAuthCollectionToolsMap = {
-  [K in MCPCollectionAuthToolName]?: MCPBuiltInToolOverride | true
+  [K in MCPCollectionAuthToolName]?: MCPBuiltInCollectionToolOverride | true
 } & MCPCollectionToolsMap
 
 /** Auth-enabled collections get auth-tool name autocomplete; others get CRUD-only. */
@@ -157,9 +193,9 @@ export type MCPToolsMapForCollection<Slug extends CollectionSlug> = Slug extends
   : MCPCollectionToolsMap
 
 export type MCPGlobalToolsMap = {
-  [customToolName: string]: boolean | GlobalTool | MCPBuiltInToolOverride | undefined
+  [customToolName: string]: boolean | GlobalTool | MCPBuiltInGlobalToolOverride | undefined
 } & {
-  [K in MCPGlobalBuiltinName]?: false | MCPBuiltInToolOverride
+  [K in MCPGlobalBuiltinName]?: false | MCPBuiltInGlobalToolOverride
 }
 
 export type MCPTopLevelToolsMap = Record<string, Tool>
@@ -171,6 +207,12 @@ export type PromptHandlerArgs<TSchema = undefined> = {
 }
 
 export type Prompt<TSchema extends ToolInputSchema = ToolInputSchema> = {
+  /**
+   * Runs while authorizing each MCP request, before the prompt is advertised or used. Return
+   * `false` to make the prompt unavailable for that request. This is skipped when
+   * `overrideAccess` is enabled.
+   */
+  access?: (args: MCPAccessArgs) => MaybePromise<boolean>
   argsSchema: TSchema
   description: string
   handler: (args: PromptHandlerArgs<TSchema>) => MaybePromise<{
@@ -188,6 +230,12 @@ export type ResourceHandlerArgs = {
 }
 
 export type Resource = {
+  /**
+   * Runs while authorizing each MCP request, before the resource is advertised or read. Return
+   * `false` to make the resource unavailable for that request. This is skipped when
+   * `overrideAccess` is enabled.
+   */
+  access?: (args: MCPAccessArgs) => MaybePromise<boolean>
   description: string
   handler: (args: ResourceHandlerArgs) => MaybePromise<{
     contents: Array<{ text: string; uri: string }>
@@ -221,34 +269,39 @@ export type MCPPluginConfig = {
   collections?: {
     [Slug in CollectionSlug]?: MCPPluginCollectionConfig<Slug>
   }
-  /** Skip MCP registration. The API key collection is still added (so DB / types stay stable). */
+  /** Skip MCP endpoint registration. */
   disabled?: boolean
   globals?: {
     [Slug in GlobalSlug]?: MCPPluginGlobalConfig
   }
+  hooks?: {
+    /** Transform a tool response after its handler returns */
+    afterToolCall?: MCPAfterToolCallHook[]
+  }
   mcp?: {
     serverOptions?: MCPServerOptions
     verboseLogs?: boolean
   }
-  overrideApiKeyCollection?: (collection: CollectionConfig) => CollectionConfig
-  /** Replace the default API-key auth with a custom resolver. */
-  overrideAuth?: (args: {
-    getAPIKeyDoc: (overrideApiKey?: string) => Promise<MCPAPIKeysDoc>
-    getAuthorizedMCP: (args: { apiKeyDoc: MCPAPIKeysDoc }) => AuthorizedMCP
-    pluginConfig: SanitizedMCPPluginConfig
-    req: PayloadRequest
-  }) => MaybePromise<AuthorizedMCP>
+  /**
+   * Replace the default MCP authorization resolver.
+   *
+   * This hook replaces the default authentication flow. It must set `req.user` to the
+   * authenticated Payload user, or to `null` for an anonymous caller, before returning.
+   */
+  overrideGetAuthorizedMCP?: (
+    args: {
+      pluginConfig: SanitizedMCPPluginConfig
+    } & GetAuthorizedMCPArgs,
+  ) => MaybePromise<AuthorizedMCP>
   prompts?: Record<string, Prompt>
   resources?: Record<string, Resource>
   /** Cross-cutting tools (not scoped to any collection or global). */
   tools?: MCPTopLevelToolsMap
-  userCollection?: CollectionSlug
 }
 
 export type SanitizedMCPPluginConfig = {
   items: MCPItem[]
-  userCollection: CollectionSlug
-} & Pick<MCPPluginConfig, 'disabled' | 'mcp' | 'overrideApiKeyCollection' | 'overrideAuth'>
+} & Pick<MCPPluginConfig, 'disabled' | 'hooks' | 'mcp' | 'overrideGetAuthorizedMCP'>
 
 export type MCPServerOptions = {
   options?: ConstructorParameters<typeof McpServer>[1]
@@ -256,52 +309,12 @@ export type MCPServerOptions = {
 }
 
 /**
- * Nested access tree as stored in the collection.
- * A `false` leaf disables that tool; missing keys defer to
- * defaults (built-in CRUD is on, opt-in tools are off).
- */
-export type MCPAPIKeysDocAccessTree = {
-  collections?: {
-    [CollectionSlug: CollectionSlug]: {
-      [ToolKey: string]: boolean
-    }
-  }
-  globals?: {
-    [GlobalSlug: GlobalSlug]: {
-      [ToolKey: string]: boolean
-    }
-  }
-  prompts?: {
-    [PromptKey: string]: boolean
-  }
-  resources?: {
-    [ResourceKey: string]: boolean
-  }
-  tools?: {
-    [ToolKey: string]: boolean
-  }
-}
-
-/**
- * Stored on `payload-mcp-api-keys` docs
- */
-export type MCPAPIKeysDoc = {
-  access: MCPAPIKeysDocAccessTree
-  apiKey?: string
-  apiKeyIndex?: string
-  id: DefaultDocumentIDType
-  lastUsed?: string
-  overrideAccess?: boolean
-  user: null | TypedUser
-}
-
-/**
- * One MCP primitive plus the metadata needed for access checks, admin UI, and
+ * One MCP primitive plus the metadata needed for config-driven filtering and
  * registration.
  *
- * - `configKey`: the config/API-key identifier, e.g. `find` or `echo`.
+ * - `configKey`: the config identifier, e.g. `find` or `echo`.
  * - `mcpName`: the MCP wire name, e.g. `findDocuments` or `echo`.
- * - `label`: human-readable admin checkbox text.
+ * - `label`: human-readable display text.
  */
 export type MCPItemBase = {
   configKey: string
@@ -338,13 +351,10 @@ export type MCPItem =
   | GlobalMCPItem
 
 /**
- * The caller's identity + the MCP items they can use for this request. Returned
- * by `getAuthorizedMCP`; denied items are simply absent from `items`. Handlers
- * receive this via `args.authorizedMCP` so they can spread
- * `localAPIDefaults(authorizedMCP)` into every local API call.
+ * The MCP items and access mode authorized for this request. The authenticated user is available
+ * as `req.user`.
  */
 export type AuthorizedMCP = {
   items: MCPItem[]
   overrideAccess: boolean
-  user: null | TypedUser
 }

package/src/utils/getPluginConfig.ts

@@ -5,7 +5,7 @@ import type { SanitizedMCPPluginConfig } from '../types.js'
 /**
  * Returns the sanitized plugin config — the form produced by
  * `sanitizeMCPConfig` and stashed back on the plugin's `options` during init.
- * Callers downstream of plugin init can rely on `items`, `userCollection`, etc.
+ * Callers downstream of plugin init can rely on `items` and other defaults
  * being fully resolved.
  */
 export const getPluginConfig: (args: { config: SanitizedConfig }) => SanitizedMCPPluginConfig = ({