Payload MCP Granular Plugin

A plugin for Payload that derives from the official @payloadcms/plugin-mcp package and adds field-level granularity for collection find, create, and update operations.

What It Adds

• Backward-compatible support for the official enabled: true and enabled: { ... } MCP config
• New granularity config for collections
• API key UI that lets admins choose which top-level fields each MCP key can find, create, and update
• MCP tool schemas filtered down to only the allowed fields for the current API key
• Runtime field access wrappers so non-allowed fields are discarded on writes and omitted on reads during MCP traffic

Requirements

• Payload ^3.80.0
• A project already using or ready to use Payload's MCP plugin model

Installation

pnpm add payload-plugin-mcp-granular

Quick Start

import { buildConfig } from 'payload'
import { mcpPlugin } from 'payload-plugin-mcp-granular'

export default buildConfig({
  collections: [
    {
      slug: 'students',
      fields: [
        { name: 'name', type: 'text' },
        { name: 'email', type: 'email' },
        { name: 'notes', type: 'textarea' },
      ],
    },
  ],
  plugins: [
    mcpPlugin({
      collections: {
        students: {
          enabled: {
            find: true,
            update: true,
          },
          granularity: {
            find: true,
            update: true,
          },
        },
      },
    }),
  ],
})

With the config above, the admin UI for each MCP API key will expose find / update toggles for students, and once enabled it will reveal field checkboxes such as name, email, and notes.

Granularity Config

You can enable granular field control in two ways.

Apply it to all enabled field-based operations:

collections: {
  students: {
    enabled: {
      find: true,
      create: true,
      update: true,
      delete: true,
    },
    granularity: true,
  },
}

Or apply it per operation:

collections: {
  students: {
    enabled: {
      find: true,
      update: true,
    },
    granularity: {
      find: true,
      update: true,
    },
  },
}

How API Key Permissions Work

There are still two layers of access, just like the official plugin:

1. Enable the collection and operations in your Payload config.
2. Create an MCP API key in the admin panel and allow the exact operations for that key.

When granularity is enabled for a collection operation:

• Turning on find, create, or update for that collection reveals a second group of field checkboxes
• Each checkbox represents one top-level field from the collection
• Only the checked fields are exposed in the MCP tool schema for create / update
• Only the checked fields are allowed at runtime for MCP traffic

Behavior Notes

• Granularity is currently supported for collections only
• Granularity is top-level only in v1
• delete remains collection-level only
• Globals keep the upstream plugin behavior
• If an operation is enabled for a key but no fields are selected, that granular MCP tool is treated as disabled for that key
• Non-MCP traffic is not affected

Example Behavior

If you configure:

collections: {
  students: {
    enabled: {
      find: true,
      update: true,
    },
    granularity: {
      find: true,
      update: true,
    },
  },
}

And in the API key UI you allow:

• students.update = true
• students.updateFields.name = true
• students.find = true
• students.findFields.name = true

Then:

• the MCP client can update the name field
• the MCP client cannot update email, notes, or other top-level fields
• findStudents responses only expose name plus normal system metadata such as id

Local Development

Build the package:

pnpm install
pnpm build

Create a tarball to test in another Payload app:

npm pack

Related Links

• Official plugin source: payloadcms/payload/packages/plugin-mcp
• Official plugin docs: Payload MCP Plugin Docs