@payloadcms/plugin-mcp 4.0.0-internal.688c4d0 → 4.0.0-internal.697830c

package/src/types.ts

@@ -6,18 +6,18 @@ import type {
   ResourceTemplate,
   ServerContext,
   StandardSchemaWithJSON,
+  ToolAnnotations,
 } 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,
@@ -26,36 +26,16 @@ import type {
 
 export type { MCPCollectionAuthToolName, MCPCollectionBuiltinName, MCPGlobalBuiltinName }
 
-/** Re-exported from `@modelcontextprotocol/server` — the JSON Schema shape the MCP runtime validates against. */
-export type { JsonSchemaType, StandardSchemaWithJSON }
+/** Re-exported from `@modelcontextprotocol/server` — common MCP types used in plugin config. */
+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[]
   /**
@@ -72,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>`.
@@ -82,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>
@@ -98,6 +98,13 @@ 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>
   input?: TSchema
@@ -110,22 +117,54 @@ 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, 'description' | 'overrideResponse'>
+} & 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, 'description' | 'overrideResponse'>
+  } & Pick<Tool, 'annotations' | 'description' | 'overrideResponse'>
 
 /**
  * Configures (or disables) a built-in tool without replacing it.
  * `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
   overrideResponse?: MCPResponseOverride
@@ -139,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. */
@@ -154,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>
@@ -168,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<{
@@ -185,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 }>
@@ -218,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]
@@ -253,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
@@ -335,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 = ({

package/src/utils/schemaConversion/filterFieldsByAccess.ts

@@ -0,0 +1,123 @@
+import type {
+  FlattenedBlock,
+  FlattenedField,
+  Operation,
+  SanitizedDocumentPermissions,
+  SanitizedFieldsPermissions,
+} from 'payload'
+
+type FieldOperation = Exclude<Operation, 'delete'>
+type AllowedFieldOperations = Record<FieldOperation, boolean>
+
+/**
+ * Filters fields using the access results in `permissions`. `shouldExcludeField` receives the
+ * operations allowed by the entity, field, and its parents and decides whether to remove the
+ * field.
+ *
+ * Arrays, groups, named tabs, and blocks are filtered recursively. Rows and unnamed tabs are
+ * flattened by Payload, so their children are filtered at the containing level.
+ *
+ * @example Include fields writable through any collection operation the user can perform.
+ * ```ts
+ * filterFieldsByAccess({
+ *   fields,
+ *   permissions: collectionPermissions,
+ *   shouldExcludeField: ({ create, update }) => !create && !update,
+ * })
+ * ```
+ */
+export const filterFieldsByAccess = ({
+  blocks,
+  fields,
+  permissions,
+  shouldExcludeField,
+}: {
+  blocks?: FlattenedBlock[]
+  fields: FlattenedField[]
+  permissions: SanitizedDocumentPermissions
+  shouldExcludeField: (allowedOperations: AllowedFieldOperations) => boolean
+}): FlattenedField[] => {
+  const filterFields = (
+    nestedFields: FlattenedField[],
+    nestedPermissions: SanitizedFieldsPermissions | undefined,
+    parentAllowedOperations: AllowedFieldOperations,
+  ): FlattenedField[] => {
+    const accessibleFields: FlattenedField[] = []
+
+    for (const field of nestedFields) {
+      const fieldPermissions = nestedPermissions === true ? true : nestedPermissions?.[field.name]
+      const isOperationAllowed = (operation: FieldOperation): boolean =>
+        parentAllowedOperations[operation] &&
+        (fieldPermissions === true || fieldPermissions?.[operation] === true)
+      const allowedOperations: AllowedFieldOperations = {
+        create: isOperationAllowed('create'),
+        read: isOperationAllowed('read'),
+        update: isOperationAllowed('update'),
+      }
+
+      if (shouldExcludeField(allowedOperations)) {
+        continue
+      }
+
+      if (field.type === 'blocks') {
+        const accessibleBlocks: (FlattenedBlock | string)[] = []
+
+        for (const blockOrReference of field.blocks) {
+          const block =
+            typeof blockOrReference === 'string'
+              ? blocks?.find(({ slug }) => slug === blockOrReference)
+              : blockOrReference
+
+          if (!block) {
+            continue
+          }
+
+          const blockPermissions =
+            fieldPermissions === true
+              ? true
+              : fieldPermissions?.blocks === true
+                ? true
+                : fieldPermissions?.blocks?.[block.slug]
+
+          accessibleBlocks.push({
+            ...block,
+            flattenedFields: filterFields(
+              block.flattenedFields,
+              blockPermissions === true ? true : blockPermissions?.fields,
+              allowedOperations,
+            ),
+          })
+        }
+
+        if (accessibleBlocks.length === 0) {
+          continue
+        }
+
+        accessibleFields.push({ ...field, blocks: accessibleBlocks })
+        continue
+      }
+
+      if (field.type === 'array' || field.type === 'group' || field.type === 'tab') {
+        accessibleFields.push({
+          ...field,
+          flattenedFields: filterFields(
+            field.flattenedFields,
+            fieldPermissions === true ? true : fieldPermissions?.fields,
+            allowedOperations,
+          ),
+        })
+        continue
+      }
+
+      accessibleFields.push(field)
+    }
+
+    return accessibleFields
+  }
+
+  return filterFields(fields, permissions.fields, {
+    create: 'create' in permissions && permissions.create === true,
+    read: permissions.read === true,
+    update: permissions.update === true,
+  })
+}

package/src/utils/schemaConversion/getEntityInputSchema.ts

@@ -1,26 +1,27 @@
 import {
   type CollectionSlug,
   entityToStandaloneJSONSchema,
+  type FlattenedField,
   type GlobalSlug,
   type PayloadRequest,
   type SanitizedCollectionConfig,
+  type SanitizedCollectionPermission,
   type SanitizedGlobalConfig,
+  type SanitizedGlobalPermission,
 } from 'payload'
 
 import type { JsonSchemaType } from '../../types.js'
 
-import {
-  getCollectionVirtualFieldNames,
-  getGlobalVirtualFieldNames,
-} from '../getVirtualFieldNames.js'
-import { removeVirtualFieldsFromSchema } from './removeVirtualFieldsFromSchema.js'
+import { filterFieldsByAccess } from './filterFieldsByAccess.js'
 import { sanitizeEntitySchema } from './sanitizeEntitySchema.js'
 
 export const getCollectionInputSchema = ({
   collectionSlug,
+  permissions,
   req,
 }: {
   collectionSlug: CollectionSlug
+  permissions?: SanitizedCollectionPermission
   req: PayloadRequest
 }): JsonSchemaType | null => {
   const collection = req.payload.collections[collectionSlug]?.config
@@ -29,18 +30,27 @@ export const getCollectionInputSchema = ({
     return null
   }
 
-  return buildEntityInputSchema({
-    entity: collection,
-    req,
-    virtualFieldNames: getCollectionVirtualFieldNames(req.payload.config, collectionSlug),
+  if (!permissions) {
+    return buildEntityInputSchema({ entity: collection, req })
+  }
+
+  const fieldsAllowedByAccess = filterFieldsByAccess({
+    blocks: req.payload.config.blocks,
+    fields: collection.flattenedFields,
+    permissions,
+    shouldExcludeField: ({ create, update }) => !create && !update,
   })
+
+  return buildEntityInputSchema({ entity: collection, fields: fieldsAllowedByAccess, req })
 }
 
 export const getGlobalInputSchema = ({
   globalSlug,
+  permissions,
   req,
 }: {
   globalSlug: GlobalSlug
+  permissions?: SanitizedGlobalPermission
   req: PayloadRequest
 }): JsonSchemaType | null => {
   const global = req.payload.config.globals.find((globalConfig) => globalConfig.slug === globalSlug)
@@ -49,30 +59,38 @@ export const getGlobalInputSchema = ({
     return null
   }
 
-  return buildEntityInputSchema({
-    entity: global,
-    req,
-    virtualFieldNames: getGlobalVirtualFieldNames(req.payload.config, globalSlug),
+  if (!permissions) {
+    return buildEntityInputSchema({ entity: global, req })
+  }
+
+  const fieldsAllowedByAccess = filterFieldsByAccess({
+    blocks: req.payload.config.blocks,
+    fields: global.flattenedFields,
+    permissions,
+    shouldExcludeField: ({ create, update }) => !create && !update,
   })
+
+  return buildEntityInputSchema({ entity: global, fields: fieldsAllowedByAccess, req })
 }
 
 const buildEntityInputSchema = ({
   entity,
+  fields = entity.flattenedFields,
   req,
-  virtualFieldNames,
 }: {
   entity: SanitizedCollectionConfig | SanitizedGlobalConfig
+  fields?: FlattenedField[]
   req: PayloadRequest
-  virtualFieldNames: string[]
-}): JsonSchemaType =>
-  sanitizeEntitySchema(
-    removeVirtualFieldsFromSchema(
-      entityToStandaloneJSONSchema({
-        config: req.payload.config,
-        defaultIDType: req.payload.db.defaultIDType,
-        entity,
-        i18n: req.i18n,
-      }) as unknown as JsonSchemaType,
-      virtualFieldNames,
-    ),
-  )
+}): JsonSchemaType => {
+  // The core schema generator reads flattenedFields from the entity and has no fields argument.
+  const entityForSchema = { ...entity, flattenedFields: fields }
+  const schema = entityToStandaloneJSONSchema({
+    config: req.payload.config,
+    defaultIDType: req.payload.db.defaultIDType,
+    entity: entityForSchema,
+    i18n: req.i18n,
+    variant: 'input',
+  }) as unknown as JsonSchemaType
+
+  return sanitizeEntitySchema(schema)
+}

package/src/utils/schemaConversion/sanitizeEntitySchema.spec.ts

@@ -5,10 +5,11 @@ import type { JsonSchemaType } from '../../types.js'
 import { sanitizeEntitySchema } from './sanitizeEntitySchema.js'
 
 describe('sanitizeEntitySchema', () => {
-  it('keeps a Lexical node union strict (oneOf) while simplifying relationship values to IDs', () => {
-    // Shaped like the schema the MCP server prepares for a collection with a Lexical richText field:
-    // a `$defs` node union (a `oneOf` of node shapes) where a relationship node's `value` is either
-    // an ID or a `$ref` to the populated related collection.
+  it('renames the Lexical node-union definition to a short name and keeps it a strict oneOf', () => {
+    // Shaped like the schema the MCP server prepares for a collection with a Lexical richText field
+    // (Payload's `input` variant): a `$defs` node union (a `oneOf` of node shapes). The input variant
+    // already types the relationship node's `value` as a bare ID - there is no populated-doc `$ref` to
+    // reduce here (the variant did that upstream), so sanitize leaves the value untouched.
     const standalone: JsonSchemaType = {
       type: 'object',
       $defs: {
@@ -25,17 +26,12 @@ describe('sanitizeEntitySchema', () => {
               additionalProperties: false,
               properties: {
                 type: { const: 'relationship' },
-                value: { oneOf: [{ type: 'string' }, { $ref: '#/$defs/posts' }] },
+                value: { type: 'string', description: 'The related document ID.' },
               },
               required: ['type'],
             },
           ],
         },
-        posts: {
-          type: 'object',
-          additionalProperties: false,
-          properties: { id: { type: 'string' }, title: { type: 'string' } },
-        },
       },
       properties: {
         id: { type: 'string' },
@@ -57,7 +53,7 @@ describe('sanitizeEntitySchema', () => {
       type: 'object',
       $defs: {
         // The node union is renamed to a short, readable `node`, and stays a strict discriminated
-        // `oneOf` - not loosened to `anyOf`...
+        // `oneOf` - not loosened to `anyOf`.
         node: {
           oneOf: [
             {
@@ -71,21 +67,18 @@ describe('sanitizeEntitySchema', () => {
               additionalProperties: false,
               properties: {
                 type: { const: 'relationship' },
-                // ...while the relationship `value` is simplified to a bare ID (the populated-doc `$ref` is dropped).
-                value: { type: 'string', description: 'The ID of the related "posts" document.' },
+                // The value is already ID-only from the input variant - left as-is.
+                value: { type: 'string', description: 'The related document ID.' },
               },
               required: ['type'],
             },
           ],
         },
-        posts: {
-          type: 'object',
-          additionalProperties: false,
-          properties: { id: { type: 'string' }, title: { type: 'string' } },
-        },
       },
       properties: {
-        // `id` is dropped - it's a Payload-managed field MCP clients never set.
+        // Managed fields (createdAt/updatedAt/_status) are excluded upstream by the `input` variant;
+        // `id` stays because it's a valid optional input (a client may supply a custom ID).
+        id: { type: 'string' },
         content: {
           type: 'object',
           properties: {