@payloadcms/plugin-mcp 4.0.0-canary.0 → 4.0.0-canary.2

package/dist/utils/schemaConversion/sanitizeEntitySchema.spec.js

@@ -0,0 +1,158 @@
+import { describe, expect, it } from 'vitest';
+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.
+        const standalone = {
+            type: 'object',
+            $defs: {
+                LexicalNodes_ABCDEF12: {
+                    oneOf: [
+                        {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                type: {
+                                    const: 'paragraph'
+                                }
+                            },
+                            required: [
+                                'type'
+                            ]
+                        },
+                        {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                type: {
+                                    const: 'relationship'
+                                },
+                                value: {
+                                    oneOf: [
+                                        {
+                                            type: 'string'
+                                        },
+                                        {
+                                            $ref: '#/$defs/posts'
+                                        }
+                                    ]
+                                }
+                            },
+                            required: [
+                                'type'
+                            ]
+                        }
+                    ]
+                },
+                posts: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        id: {
+                            type: 'string'
+                        },
+                        title: {
+                            type: 'string'
+                        }
+                    }
+                }
+            },
+            properties: {
+                id: {
+                    type: 'string'
+                },
+                content: {
+                    type: 'object',
+                    properties: {
+                        root: {
+                            type: 'object',
+                            properties: {
+                                children: {
+                                    type: 'array',
+                                    items: {
+                                        $ref: '#/$defs/LexicalNodes_ABCDEF12'
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        };
+        expect(sanitizeEntitySchema(standalone)).toStrictEqual({
+            type: 'object',
+            $defs: {
+                // The node union is renamed to a short, readable `node`, and stays a strict discriminated
+                // `oneOf` - not loosened to `anyOf`...
+                node: {
+                    oneOf: [
+                        {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                type: {
+                                    const: 'paragraph'
+                                }
+                            },
+                            required: [
+                                'type'
+                            ]
+                        },
+                        {
+                            type: 'object',
+                            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.'
+                                }
+                            },
+                            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.
+                content: {
+                    type: 'object',
+                    properties: {
+                        root: {
+                            type: 'object',
+                            properties: {
+                                children: {
+                                    type: 'array',
+                                    items: {
+                                        $ref: '#/$defs/node'
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        });
+    });
+});
+
+//# sourceMappingURL=sanitizeEntitySchema.spec.js.map

package/dist/utils/schemaConversion/sanitizeEntitySchema.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/utils/schemaConversion/sanitizeEntitySchema.spec.ts"],"sourcesContent":["import { describe, expect, it } from 'vitest'\n\nimport type { JsonSchemaType } from '../../types.js'\n\nimport { sanitizeEntitySchema } from './sanitizeEntitySchema.js'\n\ndescribe('sanitizeEntitySchema', () => {\n  it('keeps a Lexical node union strict (oneOf) while simplifying relationship values to IDs', () => {\n    // Shaped like the schema the MCP server prepares for a collection with a Lexical richText field:\n    // a `$defs` node union (a `oneOf` of node shapes) where a relationship node's `value` is either\n    // an ID or a `$ref` to the populated related collection.\n    const standalone: JsonSchemaType = {\n      type: 'object',\n      $defs: {\n        LexicalNodes_ABCDEF12: {\n          oneOf: [\n            {\n              type: 'object',\n              additionalProperties: false,\n              properties: { type: { const: 'paragraph' } },\n              required: ['type'],\n            },\n            {\n              type: 'object',\n              additionalProperties: false,\n              properties: {\n                type: { const: 'relationship' },\n                value: { oneOf: [{ type: 'string' }, { $ref: '#/$defs/posts' }] },\n              },\n              required: ['type'],\n            },\n          ],\n        },\n        posts: {\n          type: 'object',\n          additionalProperties: false,\n          properties: { id: { type: 'string' }, title: { type: 'string' } },\n        },\n      },\n      properties: {\n        id: { type: 'string' },\n        content: {\n          type: 'object',\n          properties: {\n            root: {\n              type: 'object',\n              properties: {\n                children: { type: 'array', items: { $ref: '#/$defs/LexicalNodes_ABCDEF12' } },\n              },\n            },\n          },\n        },\n      },\n    }\n\n    expect(sanitizeEntitySchema(standalone)).toStrictEqual({\n      type: 'object',\n      $defs: {\n        // The node union is renamed to a short, readable `node`, and stays a strict discriminated\n        // `oneOf` - not loosened to `anyOf`...\n        node: {\n          oneOf: [\n            {\n              type: 'object',\n              additionalProperties: false,\n              properties: { type: { const: 'paragraph' } },\n              required: ['type'],\n            },\n            {\n              type: 'object',\n              additionalProperties: false,\n              properties: {\n                type: { const: 'relationship' },\n                // ...while the relationship `value` is simplified to a bare ID (the populated-doc `$ref` is dropped).\n                value: { type: 'string', description: 'The ID of the related \"posts\" document.' },\n              },\n              required: ['type'],\n            },\n          ],\n        },\n        posts: {\n          type: 'object',\n          additionalProperties: false,\n          properties: { id: { type: 'string' }, title: { type: 'string' } },\n        },\n      },\n      properties: {\n        // `id` is dropped - it's a Payload-managed field MCP clients never set.\n        content: {\n          type: 'object',\n          properties: {\n            root: {\n              type: 'object',\n              properties: {\n                children: { type: 'array', items: { $ref: '#/$defs/node' } },\n              },\n            },\n          },\n        },\n      },\n    })\n  })\n})\n"],"names":["describe","expect","it","sanitizeEntitySchema","standalone","type","$defs","LexicalNodes_ABCDEF12","oneOf","additionalProperties","properties","const","required","value","$ref","posts","id","title","content","root","children","items","toStrictEqual","node","description"],"mappings":"AAAA,SAASA,QAAQ,EAAEC,MAAM,EAAEC,EAAE,QAAQ,SAAQ;AAI7C,SAASC,oBAAoB,QAAQ,4BAA2B;AAEhEH,SAAS,wBAAwB;IAC/BE,GAAG,0FAA0F;QAC3F,iGAAiG;QACjG,gGAAgG;QAChG,yDAAyD;QACzD,MAAME,aAA6B;YACjCC,MAAM;YACNC,OAAO;gBACLC,uBAAuB;oBACrBC,OAAO;wBACL;4BACEH,MAAM;4BACNI,sBAAsB;4BACtBC,YAAY;gCAAEL,MAAM;oCAAEM,OAAO;gCAAY;4BAAE;4BAC3CC,UAAU;gCAAC;6BAAO;wBACpB;wBACA;4BACEP,MAAM;4BACNI,sBAAsB;4BACtBC,YAAY;gCACVL,MAAM;oCAAEM,OAAO;gCAAe;gCAC9BE,OAAO;oCAAEL,OAAO;wCAAC;4CAAEH,MAAM;wCAAS;wCAAG;4CAAES,MAAM;wCAAgB;qCAAE;gCAAC;4BAClE;4BACAF,UAAU;gCAAC;6BAAO;wBACpB;qBACD;gBACH;gBACAG,OAAO;oBACLV,MAAM;oBACNI,sBAAsB;oBACtBC,YAAY;wBAAEM,IAAI;4BAAEX,MAAM;wBAAS;wBAAGY,OAAO;4BAAEZ,MAAM;wBAAS;oBAAE;gBAClE;YACF;YACAK,YAAY;gBACVM,IAAI;oBAAEX,MAAM;gBAAS;gBACrBa,SAAS;oBACPb,MAAM;oBACNK,YAAY;wBACVS,MAAM;4BACJd,MAAM;4BACNK,YAAY;gCACVU,UAAU;oCAAEf,MAAM;oCAASgB,OAAO;wCAAEP,MAAM;oCAAgC;gCAAE;4BAC9E;wBACF;oBACF;gBACF;YACF;QACF;QAEAb,OAAOE,qBAAqBC,aAAakB,aAAa,CAAC;YACrDjB,MAAM;YACNC,OAAO;gBACL,0FAA0F;gBAC1F,uCAAuC;gBACvCiB,MAAM;oBACJf,OAAO;wBACL;4BACEH,MAAM;4BACNI,sBAAsB;4BACtBC,YAAY;gCAAEL,MAAM;oCAAEM,OAAO;gCAAY;4BAAE;4BAC3CC,UAAU;gCAAC;6BAAO;wBACpB;wBACA;4BACEP,MAAM;4BACNI,sBAAsB;4BACtBC,YAAY;gCACVL,MAAM;oCAAEM,OAAO;gCAAe;gCAC9B,sGAAsG;gCACtGE,OAAO;oCAAER,MAAM;oCAAUmB,aAAa;gCAA0C;4BAClF;4BACAZ,UAAU;gCAAC;6BAAO;wBACpB;qBACD;gBACH;gBACAG,OAAO;oBACLV,MAAM;oBACNI,sBAAsB;oBACtBC,YAAY;wBAAEM,IAAI;4BAAEX,MAAM;wBAAS;wBAAGY,OAAO;4BAAEZ,MAAM;wBAAS;oBAAE;gBAClE;YACF;YACAK,YAAY;gBACV,wEAAwE;gBACxEQ,SAAS;oBACPb,MAAM;oBACNK,YAAY;wBACVS,MAAM;4BACJd,MAAM;4BACNK,YAAY;gCACVU,UAAU;oCAAEf,MAAM;oCAASgB,OAAO;wCAAEP,MAAM;oCAAe;gCAAE;4BAC7D;wBACF;oBACF;gBACF;YACF;QACF;IACF;AACF"}

package/dist/utils/whereSchema.d.ts

@@ -0,0 +1,9 @@
+import type { Where } from 'payload';
+import { z } from 'zod';
+/**
+ * - Validates the `where` input of collection tools against Payload's `Where` shape
+ * - Field keys map to operator objects restricted to `validOperators`
+ * - `and` / `or` nest recursively
+ */
+export declare const whereSchema: z.ZodType<Where>;
+//# sourceMappingURL=whereSchema.d.ts.map

package/dist/utils/whereSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whereSchema.d.ts","sourceRoot":"","sources":["../../src/utils/whereSchema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAGpC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAMvB;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CASqD,CAAA"}

package/dist/utils/whereSchema.js

@@ -0,0 +1,13 @@
+import { validOperators } from 'payload/shared';
+import { z } from 'zod';
+const whereFieldSchema = z.partialRecord(z.enum(validOperators), z.unknown()).describe('Field query operators');
+/**
+ * - Validates the `where` input of collection tools against Payload's `Where` shape
+ * - Field keys map to operator objects restricted to `validOperators`
+ * - `and` / `or` nest recursively
+ */ export const whereSchema = z.lazy(()=>z.object({
+        and: z.array(whereSchema).optional(),
+        or: z.array(whereSchema).optional()
+    }).catchall(whereFieldSchema)).describe('Where clause using field names with Payload query operators, plus and/or groups');
+
+//# sourceMappingURL=whereSchema.js.map

package/dist/utils/whereSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/whereSchema.ts"],"sourcesContent":["import type { Where } from 'payload'\n\nimport { validOperators } from 'payload/shared'\nimport { z } from 'zod'\n\nconst whereFieldSchema = z\n  .partialRecord(z.enum(validOperators), z.unknown())\n  .describe('Field query operators')\n\n/**\n * - Validates the `where` input of collection tools against Payload's `Where` shape\n * - Field keys map to operator objects restricted to `validOperators`\n * - `and` / `or` nest recursively\n */\nexport const whereSchema: z.ZodType<Where> = z\n  .lazy(() =>\n    z\n      .object({\n        and: z.array(whereSchema).optional(),\n        or: z.array(whereSchema).optional(),\n      })\n      .catchall(whereFieldSchema),\n  )\n  .describe('Where clause using field names with Payload query operators, plus and/or groups')\n"],"names":["validOperators","z","whereFieldSchema","partialRecord","enum","unknown","describe","whereSchema","lazy","object","and","array","optional","or","catchall"],"mappings":"AAEA,SAASA,cAAc,QAAQ,iBAAgB;AAC/C,SAASC,CAAC,QAAQ,MAAK;AAEvB,MAAMC,mBAAmBD,EACtBE,aAAa,CAACF,EAAEG,IAAI,CAACJ,iBAAiBC,EAAEI,OAAO,IAC/CC,QAAQ,CAAC;AAEZ;;;;CAIC,GACD,OAAO,MAAMC,cAAgCN,EAC1CO,IAAI,CAAC,IACJP,EACGQ,MAAM,CAAC;QACNC,KAAKT,EAAEU,KAAK,CAACJ,aAAaK,QAAQ;QAClCC,IAAIZ,EAAEU,KAAK,CAACJ,aAAaK,QAAQ;IACnC,GACCE,QAAQ,CAACZ,mBAEbI,QAAQ,CAAC,mFAAkF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payloadcms/plugin-mcp",
-  "version": "4.0.0-canary.0",
+  "version": "4.0.0-canary.2",
   "description": "MCP (Model Context Protocol) capabilities with Payload",
   "keywords": [
     "plugin",
@@ -56,19 +56,20 @@
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/server": "2.0.0-alpha.2",
     "tsx": "4.22.4",
-    "zod": "^4.0.0"
+    "zod": "^4.0.0",
+    "@payloadcms/translations": "4.0.0-canary.2"
   },
   "devDependencies": {
     "@types/react": "19.2.14",
     "react": "^19.0.1 || ^19.1.2 || ^19.2.1",
     "@payloadcms/eslint-config": "3.28.0",
-    "payload": "4.0.0-canary.0",
-    "@payloadcms/ui": "4.0.0-canary.0"
+    "payload": "4.0.0-canary.2",
+    "@payloadcms/ui": "4.0.0-canary.2"
   },
   "peerDependencies": {
     "react": "^19.0.1 || ^19.1.2 || ^19.2.1",
-    "@payloadcms/ui": "4.0.0-canary.0",
-    "payload": "4.0.0-canary.0"
+    "@payloadcms/ui": "4.0.0-canary.2",
+    "payload": "4.0.0-canary.2"
   },
   "//deps_notes": {
     "zod": "zod is a hard dependency of @modelcontextprotocol/server, thus we can safely use it without it impacting bundle size. Make extra sure the zod version here matches exactly what's defined in the dependencies of @modelcontextprotocol/server to avoid duplicate versions being installed.",

package/src/collection/getAccessField.ts

@@ -2,6 +2,12 @@ import type { JSONField } from 'payload'
 
 import type { ClientMCPPluginConfig, MCPItem, SanitizedMCPPluginConfig } from '../types.js'
 
+import {
+  COLLECTION_AUTH_BUILTINS,
+  COLLECTION_BUILTINS,
+  GLOBAL_BUILTINS,
+} from '../mcp/builtinTools.js'
+
 /**
  * Returns the API key collection's `access` field — a JSON field whose value
  * is the `MCPAPIKeysDocAccessTree` the endpoint consults. The actual UI is
@@ -25,13 +31,9 @@ export const getAccessField = ({
           path: '@payloadcms/plugin-mcp/client#AccessField',
         },
       },
-      // TODO: needs i18n once design is finalized
-      description: 'Access for this API key — uncheck to revoke individual tools.',
-      position: 'sidebar',
     },
     defaultValue: {},
-    // TODO: needs i18n once design is finalized
-    label: 'Access',
+    label: false,
   }
 }
 
@@ -43,14 +45,19 @@ export const getAccessField = ({
 const sanitizeClientPluginConfig = (
   pluginConfig: SanitizedMCPPluginConfig,
 ): ClientMCPPluginConfig => ({
-  items: pluginConfig.items.map((item) => ({
-    ...(item.type === 'collectionTool' ? { collectionSlug: item.collectionSlug } : {}),
-    ...(item.type === 'globalTool' ? { globalSlug: item.globalSlug } : {}),
-    type: item.type,
-    description: itemDescription(item),
-    key: item.key,
-    label: item.label,
-  })),
+  items: pluginConfig.items.map((item) => {
+    const group = itemGroup(item)
+
+    return {
+      ...(item.type === 'collectionTool' ? { collectionSlug: item.collectionSlug } : {}),
+      ...(item.type === 'globalTool' ? { globalSlug: item.globalSlug } : {}),
+      type: item.type,
+      configKey: item.configKey,
+      ...(group === 'operations' ? {} : { description: itemDescription(item) }),
+      group,
+      label: item.label,
+    }
+  }),
 })
 
 const itemDescription = (item: MCPItem): string => {
@@ -62,3 +69,16 @@ const itemDescription = (item: MCPItem): string => {
   }
   return item.tool.description
 }
+
+const itemGroup = (item: MCPItem): 'auth' | 'custom' | 'operations' | undefined => {
+  if (item.type === 'collectionTool') {
+    if (item.configKey in COLLECTION_BUILTINS) {
+      return 'operations'
+    }
+    return item.configKey in COLLECTION_AUTH_BUILTINS ? 'auth' : 'custom'
+  }
+  if (item.type === 'globalTool') {
+    return item.configKey in GLOBAL_BUILTINS ? 'operations' : 'custom'
+  }
+  return undefined
+}

package/src/collection/index.ts

@@ -1,9 +1,25 @@
 import type { CollectionConfig } from 'payload'
 
+import { createAPIKeyFields } from 'payload'
+
 import type { SanitizedMCPPluginConfig } from '../types.js'
 
 import { getAccessField } from './getAccessField.js'
 
+const apiKeyStorageFields = createAPIKeyFields({
+  apiKeyField: {
+    admin: {
+      components: { Field: '@payloadcms/plugin-mcp/client#APIKeyField' },
+    },
+    required: true,
+  },
+  apiKeyIndexField: {
+    index: true,
+    required: true,
+  },
+  includeEnableAPIKey: false,
+})
+
 export const getAPIKeysCollection = ({
   pluginConfig,
 }: {
@@ -12,49 +28,75 @@ export const getAPIKeysCollection = ({
   const collection: CollectionConfig = {
     slug: 'payload-mcp-api-keys',
     admin: {
-      description:
-        'API keys control which collections, resources, tools, and prompts MCP clients can access',
-      group: 'MCP',
+      components: {
+        views: {
+          list: {
+            NoResults: '@payloadcms/plugin-mcp/client#APIKeysEmptyState',
+          },
+        },
+      },
+      defaultColumns: ['label', 'lastUsed', 'user'],
+      // Kept out of the main nav — reachable through the user menu's settings instead.
+      group: false,
       useAsTitle: 'label',
     },
-    auth: {
-      disableLocalStrategy: true,
-      useAPIKey: true,
-    },
     fields: [
-      {
-        name: 'user',
-        type: 'relationship',
-        admin: { description: 'The user that the API key is associated with.' },
-        relationTo: pluginConfig.userCollection,
-        required: true,
-      },
+      ...apiKeyStorageFields,
+      getAccessField({ pluginConfig }),
       {
         name: 'label',
         type: 'text',
-        admin: { description: 'A useful label for the API key.' },
+        admin: {
+          description: ({ t }) => t('plugin-mcp:titleDescription'),
+          position: 'sidebar',
+        },
+        label: ({ t }) => t('plugin-mcp:title'),
       },
       {
         name: 'description',
         type: 'text',
-        admin: { description: 'The purpose of the API key.' },
+        admin: {
+          description: ({ t }) => t('plugin-mcp:descriptionDescription'),
+          position: 'sidebar',
+        },
+        label: ({ t }) => t('plugin-mcp:description'),
+      },
+      {
+        name: 'lastUsed',
+        type: 'date',
+        admin: {
+          date: { pickerAppearance: 'dayAndTime' },
+          disabled: { field: true },
+        },
+        label: ({ t }) => t('plugin-mcp:lastUsed'),
+      },
+      {
+        name: 'user',
+        type: 'relationship',
+        admin: {
+          description: ({ t }) => t('plugin-mcp:userDescription'),
+          position: 'sidebar',
+        },
+        label: ({ t }) => t('general:user'),
+        relationTo: pluginConfig.userCollection,
+        required: true,
       },
       {
         name: 'overrideAccess',
         type: 'checkbox',
         admin: {
-          description:
-            'When checked, this key bypasses Payload access control on every operation it performs. Leave unchecked unless you have a specific reason.',
+          description: ({ t }) => t('plugin-mcp:overrideAccessDescription'),
+          position: 'sidebar',
         },
         defaultValue: false,
-        label: 'Override access control',
+        label: ({ t }) => t('plugin-mcp:overrideAccess'),
       },
-      getAccessField({ pluginConfig }),
     ],
     labels: {
-      plural: 'API Keys',
-      singular: 'API Key',
+      plural: ({ t }) => `${t('plugin-mcp:mcp')} ${t('plugin-mcp:apiKeys')}`,
+      singular: ({ t }) => `${t('plugin-mcp:mcp')} ${t('authentication:apiKey')}`,
     },
+    versions: false,
   }
 
   return pluginConfig.overrideApiKeyCollection

package/src/components/APIKeyField/index.client.tsx

@@ -0,0 +1,73 @@
+'use client'
+
+import { APIKeyInput, Button, useField, useTranslation, WarningTriangleIcon } from '@payloadcms/ui'
+import React, { useState } from 'react'
+
+import type {
+  PluginMCPTranslationKeys,
+  PluginMCPTranslations,
+} from '../../translations/index.js'
+
+import './index.css'
+
+const baseClass = 'mcp-api-key-field'
+
+/**
+ * Custom component for the MCP API-keys collection's `apiKey` field:
+ * - no key yet: a "Generate new key" button
+ * - key set: a dismissible privacy warning + the shared masked-key input
+ */
+export const APIKeyField: React.FC = () => {
+  const { setValue: setApiKey, value: apiKey } = useField<string>({ path: 'apiKey' })
+  const { t } = useTranslation<PluginMCPTranslations, PluginMCPTranslationKeys>()
+  const [isWarningDismissed, setIsWarningDismissed] = useState(false)
+
+  const generateKey = () => {
+    setApiKey(crypto.randomUUID())
+    setIsWarningDismissed(false)
+  }
+
+  return (
+    <div className={baseClass}>
+      <p className={`${baseClass}__description`}>
+        {t('plugin-mcp:apiKeyDescription')}
+      </p>
+      <div className={`${baseClass}__panel`}>
+        <div className={`${baseClass}__header`}>
+          <span className={`${baseClass}__title`}>{t('authentication:apiKey')}</span>
+          {!apiKey && (
+            <Button
+              buttonStyle="primary"
+              className={`${baseClass}__generate`}
+              onClick={generateKey}
+            >
+              {t('authentication:generateNewAPIKey')}
+            </Button>
+          )}
+        </div>
+        {Boolean(apiKey) && (
+          <div className={`${baseClass}__body`}>
+            {!isWarningDismissed && (
+              <div className={`${baseClass}__warning`}>
+                <WarningTriangleIcon className={`${baseClass}__warning-icon`} />
+                <p className={`${baseClass}__warning-text`}>
+                  <strong>{t('plugin-mcp:keepKeyPrivate')}</strong>
+                  {` ${t('plugin-mcp:keyPrivateDescription')}`}
+                </p>
+                <button
+                  aria-label={t('plugin-mcp:dismiss')}
+                  className={`${baseClass}__warning-dismiss`}
+                  onClick={() => setIsWarningDismissed(true)}
+                  type="button"
+                >
+                  &times;
+                </button>
+              </div>
+            )}
+            <APIKeyInput aria-label={t('authentication:apiKey')} value={apiKey} />
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}

package/src/components/APIKeyField/index.css

@@ -0,0 +1,105 @@
+@layer payload-default {
+  /* Section wrapper: description + panel, closed off by a full-bleed divider
+     that spans the fields column past its horizontal gutter. */
+  .mcp-api-key-field {
+    display: flex;
+    flex-direction: column;
+    gap: var(--base);
+    margin-inline: calc(-1 * var(--gutter-h));
+    padding-inline: var(--gutter-h);
+    padding-block-end: var(--spacer-4);
+    border-block-end: var(--stroke-width-small) solid var(--color-border);
+  }
+
+  .mcp-api-key-field__description {
+    margin: 0;
+    color: var(--color-text);
+    font-family: var(--text-body-medium-font-family);
+    font-size: var(--text-body-medium-font-size);
+    font-weight: var(--text-body-medium-font-weight);
+    line-height: var(--text-body-medium-line-height);
+    letter-spacing: var(--text-body-medium-letter-spacing);
+  }
+
+  .mcp-api-key-field__panel {
+    overflow: hidden;
+    background: var(--color-bg);
+    border: var(--stroke-width-small) solid var(--color-border);
+    border-radius: var(--button-radius);
+  }
+
+  .mcp-api-key-field__header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--spacer-2);
+    min-height: var(--spacer-5);
+    padding: var(--spacer-2) var(--spacer-3);
+    background: var(--color-bg-secondary);
+  }
+
+  /* Holds the warning + key row; its top border is the full-width divider
+     under the header. Only rendered once a key exists. */
+  .mcp-api-key-field__body {
+    display: flex;
+    flex-direction: column;
+    gap: var(--spacer-2);
+    padding: var(--spacer-3);
+    border-block-start: var(--stroke-width-small) solid var(--color-border);
+  }
+
+  .mcp-api-key-field__title {
+    color: var(--color-text);
+    font-family: var(--text-body-medium-strong-font-family);
+    font-size: var(--text-body-medium-strong-font-size);
+    font-weight: var(--text-body-medium-strong-font-weight);
+    line-height: var(--text-body-medium-strong-line-height);
+  }
+
+  .mcp-api-key-field__generate {
+    margin: 0;
+  }
+
+  /* Matches the core Banner's warning treatment: theme-adaptive warning-tertiary
+     bg with regular --color-text (NOT --color-text-onwarning, which is only
+     defined for light mode and reads as muddy dark-on-dark in dark mode). */
+  .mcp-api-key-field__warning {
+    display: flex;
+    align-items: center;
+    gap: calc(var(--base) / 2);
+    padding: calc(var(--spacer-2) + (var(--spacer-1) / 2)) calc(var(--base) / 2);
+    background: var(--color-bg-warning-tertiary);
+    border: none;
+    border-radius: var(--radius-medium);
+    color: var(--color-text);
+  }
+
+  .mcp-api-key-field__warning-icon {
+    flex-shrink: 0;
+    width: 15px;
+    height: 13px;
+  }
+
+  .mcp-api-key-field__warning-text {
+    flex-grow: 1;
+    margin: 0;
+    font-family: var(--text-body-medium-font-family);
+    font-size: var(--text-body-medium-font-size);
+    line-height: var(--text-body-medium-line-height);
+  }
+
+  .mcp-api-key-field__warning-text strong {
+    font-weight: var(--text-body-medium-strong-font-weight);
+  }
+
+  .mcp-api-key-field__warning-dismiss {
+    appearance: none;
+    background: none;
+    border: none;
+    cursor: pointer;
+    color: inherit;
+    font-size: 1rem;
+    line-height: 1;
+    padding: 0;
+  }
+}

package/src/components/APIKeysEmptyState/index.client.tsx

@@ -0,0 +1,36 @@
+'use client'
+
+import type { NoResultsClientProps } from 'payload'
+
+import { Button, NoListResults, useTranslation } from '@payloadcms/ui'
+import React from 'react'
+
+import type {
+  PluginMCPTranslationKeys,
+  PluginMCPTranslations,
+} from '../../translations/index.js'
+
+export const APIKeysEmptyState: React.FC<NoResultsClientProps> = ({
+  hasCreatePermission,
+  newDocumentURL,
+  viewType,
+}) => {
+  const { t } = useTranslation<PluginMCPTranslations, PluginMCPTranslationKeys>()
+
+  return (
+    <NoListResults
+      Actions={
+        hasCreatePermission && newDocumentURL && viewType !== 'trash'
+          ? [
+              <Button el="link" key="create" to={newDocumentURL}>
+                {t('authentication:generateNewAPIKey')}
+              </Button>,
+            ]
+          : []
+      }
+      description={t('plugin-mcp:apiKeyDescription')}
+      title={t('plugin-mcp:noAPIKeys')}
+      withMargin
+    />
+  )
+}