@payloadcms/plugin-mcp

Exposes Payload CMS collections, globals, and custom resources as MCP tools that AI models can discover and invoke through the Model Context Protocol standard. Implements MCP server interface that translates Payload's REST/GraphQL API surface into MCP-compatible tool definitions with JSON schema validation, enabling Claude and other MCP-compatible models to read/write CMS data without direct API knowledge.

Automatically generates MCP tool definitions (with JSON schemas, descriptions, and parameter validation) from Payload collection and global configurations at runtime. Introspects Payload's field definitions, access control rules, and relationships to construct MCP-compatible tool schemas without manual tool definition, enabling tools to reflect schema changes without code redeployment.

Enables MCP tools to handle file uploads to Payload's media collection, supporting base64-encoded file data in tool parameters and automatic storage through Payload's configured storage adapter. Implements file validation, size limits, and metadata extraction, allowing AI models to upload generated or processed files directly to CMS.

Exposes Payload's versioning system through MCP tools, allowing AI models to create, retrieve, and restore document versions. Supports draft/published workflows where AI can modify drafts without affecting published content, enabling AI-assisted content editing with version history and rollback capabilities.

Executes read and write operations against Payload collections through MCP tool invocations, translating MCP tool calls into Payload API queries with full support for filtering, sorting, pagination, and field selection. Implements request validation against Payload's access control layer and field-level permissions, ensuring AI model operations respect CMS authorization rules.

Exposes Payload globals (site-wide configuration, settings, metadata) as readable and writable MCP resources, allowing AI models to access and modify global configuration through the MCP protocol. Implements globals as special MCP tools that operate on singleton documents rather than collections, with schema generation matching Payload's globals field structure.

Manages MCP server initialization, client connection handling, and authentication/authorization for Payload CMS access. Implements MCP server protocol handshake, capability negotiation, and request routing with support for API key or token-based authentication to Payload, ensuring secure communication between MCP clients and CMS resources.

Resolves Payload relationship fields and document references when returning query results through MCP, allowing AI models to access related documents and understand data relationships. Implements configurable relationship population (eager loading) with depth control to manage context window usage while providing meaningful relationship context to AI agents.

Enforces Payload's field-level access control rules on MCP tool invocations, filtering returned fields and blocking mutations on restricted fields based on the authenticated user's permissions. Implements permission checking at the MCP layer before executing Payload operations, ensuring AI models cannot access or modify fields outside their authorization scope.

Advertises available MCP tools (collections, globals, custom operations) to clients during protocol handshake, allowing AI models to discover what CMS operations are available without hardcoding tool definitions. Implements MCP capability negotiation with dynamic tool listing based on Payload schema and user permissions, enabling clients to adapt behavior based on available resources.

Supports batch create, update, and delete operations through MCP tools, allowing AI models to modify multiple documents in a single tool invocation. Implements batch processing with partial failure handling, returning success/failure status per document while maintaining transactional semantics where possible.

Exposes Payload's webhook system through MCP, allowing AI clients to subscribe to content change events and receive notifications when documents are created, updated, or deleted. Implements event filtering by collection and operation type, enabling AI agents to react to CMS changes in real-time.