Getting Started

Prerequisites

• Node.js 18.20.2+ or 20.9.0+ or 22.0.0+
• Payload CMS 3.0.0+
• pnpm 9+ (recommended) or npm

Installation

Install the plugin using your preferred package manager:

pnpm

1
pnpm add payload-plugin-mcp

npm

1
npm install payload-plugin-mcp

yarn

1
yarn add payload-plugin-mcp

Environment Setup

Create or update your .env file with the required configuration:

1
# Required: API key for MCP server authentication
2
MCP_API_KEY=your-secret-api-key-here

Tip: Generate a secure API key using a tool like openssl rand -hex 32 or use a UUID generator.

Basic Configuration

Add the plugin to your Payload configuration:

1
// payload.config.ts
2
import { buildConfig } from 'payload'
3
import { PayloadPluginMcp } from 'payload-plugin-mcp'
4

5
export default buildConfig({
6
  collections: [
7
    // your existing collections
8
  ],
9
  plugins: [
10
    PayloadPluginMcp({
11
      apiKey: process.env.MCP_API_KEY,
12
      collections: 'all', // Expose all collections
13
      defaultOperations: {
14
        list: true, // Enable listing documents
15
        get: true, // Enable getting single documents
16
        create: false, // Disable creation (read-only by default)
17
        update: false, // Disable updates (read-only by default)
18
        delete: false, // Disable deletion (read-only by default)
19
      },
20
    }),
21
  ],
22
})

Start Your Application

Start your Payload CMS application:

1
pnpm dev

You should see output similar to:

1
✅ PayloadCMS MCP Plugin initialized
2
🔧 Collections exposed: posts, users, media
3
🛠️  Tools generated: 6
4
🌐 MCP HTTP server: http://0.0.0.0:3000/api/plugin/mcp
5
🔐 Authentication: Enabled
6
   📋 posts: list, get
7
   📋 users: list, get
8
   📋 media: list, get

Verify Installation

Test that the plugin is working by making a request to the MCP endpoint:

1
curl -H "Authorization: Bearer your-api-key" http://localhost:3000/api/plugin/mcp

You should receive a response with information about available tools and the server status.

Test with MCP Inspector

Use the MCP Inspector to test your server:

1
npx @modelcontextprotocol/inspector http://localhost:3000/api/plugin/mcp

This will open the MCP Inspector at http://localhost:6274 where you can:

• Enter your Authorization header (Bearer your-api-key)
• Test MCP tool execution
• Explore available tools and their schemas
• Debug connection issues

Next Steps

• Configure collections for more advanced setups (see README.md)
• Set up Claude Desktop integration (see README.md)
• Deploy to production (see examples/vercel/)

Important: Never commit your API key to version control. Always use environment variables for sensitive configuration.