PayloadCMS MCP Plugin

1
pnpm install payload-plugin-mcp

1
openssl rand -base64 32 # => eg ACDlHFY0DoreUVnxB62dSPUU++AFg8M5W3fWy6mtyD4=

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

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 collections here
8
  ],
9
  plugins: [
10
    // other plugins...
11
    PayloadPluginMcp({
12
      apiKey: process.env.MCP_API_KEY,
13
      collections: 'all', // Expose all collections with default operations
14
      defaultOperations: {
15
        list: true,
16
        get: true,
17
        create: false,
18
        update: false,
19
        delete: false,
20
      },
21
    }),
22
  ],
23
})

1
// payload.config.ts
2
import { buildConfig } from 'payload'
3
import { PayloadPluginMcp } from 'payload-plugin-mcp'
4
// Import your collections
5
import { Posts } from './collections/Posts'
6
import { Users } from './collections/Users'
7
import { Media } from './collections/Media'
8

9
export default buildConfig({
10
  collections: [Posts, Users, Media],
11
  plugins: [
12
    PayloadPluginMcp({
13
      apiKey: process.env.MCP_API_KEY,
14
      // Pass collections directly (like Payload's native format)
15
      collections: [
16
        Posts, // Uses default operations
17
        Users, // Uses default operations
18
        Media, // Uses default operations
19
      ],
20
      defaultOperations: {
21
        list: true,
22
        get: true,
23
        create: false,
24
        update: false,
25
        delete: false,
26
      },
27
    }),
28
  ],
29
})

1
// payload.config.ts
2
import { buildConfig } from 'payload'
3
import { PayloadPluginMcp } from 'payload-plugin-mcp'
4
import { Posts } from './collections/Posts'
5
import { Users } from './collections/Users'
6
import { Media } from './collections/Media'
7

8
export default buildConfig({
9
  collections: [Posts, Users, Media],
10
  plugins: [
11
    PayloadPluginMcp({
12
      apiKey: process.env.MCP_API_KEY,
13
      collections: [
14
        // Simple collection (uses default operations)
15
        Posts,
16

17
        // Collection with custom options
18
        {
19
          collection: Users,
20
          options: {
21
            operations: {
22
              list: true,
23
              get: true,
24
              create: true, // Enable creation for users
25
              update: true, // Enable updates for users
26
              delete: false, // Keep delete disabled
27
            },
28
            toolPrefix: 'user', // Custom tool prefix
29
            description: 'user management', // Custom description
30
            excludeFields: ['password'], // Hide sensitive fields
31
          },
32
        },
33

34
        // Media with different settings
35
        {
36
          collection: Media,
37
          options: {
38
            operations: {
39
              list: true,
40
              get: true,
41
              create: true,
42
              update: false,
43
              delete: true, // Allow media deletion
44
            },
45
            toolPrefix: 'file',
46
            description: 'file storage',
47
          },
48
        },
49
      ],
50
      // Default operations for collections without specific config
51
      defaultOperations: {
52
        list: true,
53
        get: true,
54
        create: false,
55
        update: false,
56
        delete: false,
57
      },
58
    }),
59
  ],
60
})

1
pnpm dev

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

1
{
2
  "name": "posts_list",
3
  "description": "List documents from the posts collection with optional filtering, pagination, and sorting",
4
  "input": {
5
    "where": { "status": { "equals": "published" } },
6
    "limit": 10,
7
    "page": 1,
8
    "sort": "-createdAt",
9
    "depth": 1
10
  }
11
}

1
{
2
  "name": "user_create",
3
  "description": "Create a new document in the user management",
4
  "input": {
5
    "data": {
6
      "name": "John Doe",
7
      "email": "john@example.com"
8
      // Note: 'password' field excluded due to excludeFields config
9
    },
10
    "depth": 1
11
  }
12
}

1
interface CollectionMcpOptions {
2
  /**
3
   * Operations to enable for this collection
4
   */
5
  operations?: {
6
    list?: boolean // List documents with filtering/pagination
7
    get?: boolean // Get single document by ID
8
    create?: boolean // Create new documents
9
    update?: boolean // Update existing documents
10
    delete?: boolean // Delete documents
11
  }
12

13
  /**
14
   * Custom tool naming prefix (defaults to collection slug)
15
   * Example: 'user' generates 'user_list', 'user_get', etc.
16
   */
17
  toolPrefix?: string
18

19
  /**
20
   * Custom description for this collection's tools
21
   * Used in tool descriptions: "List documents from the {description}"
22
   */
23
  description?: string
24

25
  /**
26
   * Fields to exclude from schemas (useful for sensitive data)
27
   * Example: ['password', 'secret', 'internal']
28
   */
29
  excludeFields?: string[]
30

31
  /**
32
   * Additional metadata for this collection
33
   */
34
  metadata?: Record<string, any>
35
}

1
// Format 1: All collections with defaults
2
collections: 'all'
3

4
// Format 2: Direct collection imports
5
collections: [Posts, Users, Media]
6

7
// Format 3: Mixed configuration
8
collections: [
9
  Posts,                          // Uses defaults
10
  { collection: Users, options: {...} }, // Custom config
11
  Media,                          // Uses defaults
12
]

1
{
2
  "mcpServers": {
3
    "payloadcms": {
4
      "command": "npx",
5
      "args": [
6
        "-y",
7
        "mcp-remote",
8
        "https://your-domain.com/api/plugin/mcp",
9
        "--header",
10
        "Authorization: Bearer ${MCP_API_KEY}",
11
        "--header",
12
        "Content-Type: application/json"
13
      ],
14
      "env": {
15
        "MCP_API_KEY": "your-api-key"
16
      }
17
    }
18
  }
19
}

1
{
2
  "mcpServers": {
3
    "payloadcms-local": {
4
      "command": "npx",
5
      "args": [
6
        "-y",
7
        "mcp-remote",
8
        "http://localhost:3000/api/plugin/mcp",
9
        "--header",
10
        "Authorization: Bearer ${MCP_API_KEY}"
11
      ],
12
      "env": {
13
        "MCP_API_KEY": "your-api-key"
14
      }
15
    }
16
  }
17
}

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

1
curl -X POST \
2
     -H "Authorization: Bearer your-api-key" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
       "jsonrpc": "2.0",
6
       "id": 1,
7
       "method": "tools/call",
8
       "params": {
9
         "name": "posts_list",
10
         "arguments": {
11
           "where": { "status": { "equals": "published" } },
12
           "limit": 5
13
         }
14
       }
15
     }' \
16
     http://localhost:3000/api/plugin/mcp

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

1
// CMS with different access levels
2
PayloadPluginMcp({
3
  collections: [
4
    // Public content - read-only
5
    {
6
      collection: Posts,
7
      options: {
8
        operations: { list: true, get: true },
9
        description: 'blog posts',
10
      },
11
    },
12

13
    // Admin content - full access
14
    {
15
      collection: Pages,
16
      options: {
17
        operations: { list: true, get: true, create: true, update: true, delete: true },
18
        toolPrefix: 'page',
19
        description: 'website pages',
20
      },
21
    },
22

23
    // Media - managed uploads
24
    {
25
      collection: Media,
26
      options: {
27
        operations: { list: true, get: true, create: true, delete: true },
28
        toolPrefix: 'asset',
29
        description: 'media assets',
30
      },
31
    },
32
  ],
33
})

1
// E-commerce with product management
2
PayloadPluginMcp({
3
  collections: [
4
    // Products - full management
5
    {
6
      collection: Products,
7
      options: {
8
        operations: { list: true, get: true, create: true, update: true },
9
        excludeFields: ['internalNotes', 'cost'],
10
      },
11
    },
12

13
    // Orders - read and update only
14
    {
15
      collection: Orders,
16
      options: {
17
        operations: { list: true, get: true, update: true },
18
        excludeFields: ['paymentDetails'],
19
      },
20
    },
21

22
    // Categories - read-only
23
    {
24
      collection: Categories,
25
      options: {
26
        operations: { list: true, get: true },
27
      },
28
    },
29
  ],
30
})

1
openssl rand -base64 32

1
MCP_API_KEY=your-production-api-key

1
{
2
  "mcpServers": {
3
    "payloadcms-production": {
4
      "command": "npx",
5
      "args": [
6
        "-y",
7
        "mcp-remote",
8
        "https://your-app.vercel.app/api/mcp",
9
        "--header",
10
        "Authorization: Bearer ${MCP_API_KEY}",
11
        "--header",
12
        "application/json"
13
      ],
14
      "env": {
15
        "MCP_API_KEY": "your-production-api-key"
16
      }
17
    }
18
  }
19
}

1
payloadPluginMcp({
2
  // ... other options
3
  debug: true, // Enable debug logging
4
})

1
curl http://localhost:3000/api/plugin/mcp