Implementing Payload CMS + MCP: A Security-First Approach to AI Context

Author Profile: Matija
Role: Lead Engineer specializing in AI-integrated CMS architectures.
Expertise: 10+ years in full-stack development; core contributor to the Website Intelligence Briefing project; specialized in Payload CMS 3.0 and Model Context Protocol (MCP) integrations.
Updated: April 23, 2026

Purpose of This Guide

This guide is intended to help developers implement secure, auditable MCP access in Payload CMS based on a real-world deployment. It moves beyond basic "how-to" tutorials to address the architectural and security trade-offs required for production-ready AI tooling.

📝 Production Note

This article was researched and tested through a live implementation of the Website Intelligence Briefing system. The technical patterns were verified directly in a local PostgreSQL environment. AI was used for copy-editing and structural suggestions, but all technical assertions and code examples are grounded in direct testing.

🛠 Environment & Compatibility Matrix

This implementation has been verified in the following environment:

1. Architectural Strategy: Bot-Readable Schemas

When exposing a CMS to an LLM, the primary constraint is the Context Window. In our testing, flatter payloads made tool selection less reliable and increased response overhead.

Practical Implementation: Field Grouping

In our LeadPages collection, we use the collapsible component to group high-token metadata. This allows the MCP plugin to represent the data hierarchy more clearly to the model.

// src/collections/LeadPages.ts
export const LeadPages: CollectionConfig = {
  slug: 'lead_pages',
  fields: [
    { name: 'url', type: 'text', required: true },
    {
      type: 'collapsible',
      label: 'Scraping Data',
      fields: [
        { name: 'markdownContent', type: 'textarea' }, // Core content for the LLM
        { name: 'status', type: 'select', options: ['pending', 'fetched', 'failed'] },
      ],
    },
  ],
};

2. 🔐 The Authentication Distinction (Critical for Security)

A common point of failure is confusing User Auth with MCP Auth.

MCP Plugin API Keys

The plugin generates a dedicated collection: payload-mcp-api-keys.

• Decoupled Security: Connections use Authorization: Bearer YOUR_MCP_API_KEY.
• Scoped Capabilities: Each key document contains boolean toggles for every collection and operation.
• User Impersonation: Every MCP key must be associated with a standard Payload User. Payload executes actions as that user, enforcing your existing access control functions.

3. Tested Patterns & Evidence

Verified Request Pattern

To verify your connection, use curl. A successful response confirms that the Bearer token is correctly resolving through the payload-mcp-api-keys collection.

Test Command:

curl -i 'http://localhost:3000/api/mcp' \
  -X POST \
  -H 'Authorization: Bearer YOUR_MCP_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'

Real-World Failure Case: Slug Case-Sensitivity

During implementation, we encountered a 500 Error when creating keys programmatically. We discovered that the plugin converts collection slugs to camelCase for its capability fields.

• Failure: Trying to set lead_pages: { find: true }.
• Fix: Use leadPages: { find: true }.

Log Evidence (Successful Handshake)

[15:09:42] INFO (payload-mcp): API Key is valid
[15:09:42] INFO (payload-mcp): Handshake successful for user: dev-admin@example.com
POST /api/mcp 200 in 49ms

4. Security Threat Model & Best Practices

1. Secret Exposure: The .mcp.json file often contains the Bearer token. Always add .mcp.json to your .gitignore.
2. Over-Privilege: Only enable find for sensitive collections like Users. Avoid enabling delete unless specifically required.
3. Key Rotation: Treat these keys like SSH keys. Rotate them every 90 days.

5. Why This Architecture Improves Operational Trust

This setup can allow an MCP-compatible client (like Cursor, Claude, or Gemini) to query and, if explicitly permitted, modify CMS data through controlled operations defined by your access rules and key scopes. This improves maintainability and reliability by:

• Isolating AI logic: Changes to AI capabilities don't require changes to primary user auth.
• Granular Auditing: Every action taken by the AI is logged against the associated User ID.
• Predictable Tooling: Explicit descriptions in the config reduce tool-selection errors.

Resources

• Payload MCP Plugin Documentation
• Payload CMS Access Control Guide
• Model Context Protocol Specification
• Official @payloadcms/plugin-mcp Repository