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:

Enable the collection and operations in your Payload config.
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

MCP Servers