Documentation

PayloadCMS MCP Plugin

External Links

GitHub RepositoryNPM Package
Theme

API Reference

Table of Contents

Plugin Configuration

PayloadPluginMcp

The main plugin function that returns a PayloadCMS plugin configuration.

1
PayloadPluginMcp(options: McpPluginOptions): PayloadPlugin
typescript
2 lines

Parameters

  • options (McpPluginOptions): Configuration options for the MCP plugin

McpPluginOptions

1
interface McpPluginOptions {
2
  apiKey: string
3
  collections?: string[] | 'all'
4
  defaultOperations?: {
5
    list?: boolean
6
    get?: boolean
7
    create?: boolean
8
    update?: boolean
9
    delete?: boolean
10
  }
11
  server?: {
12
    port?: number
13
    host?: string
14
  }
15
  auth?: {
16
    enabled?: boolean
17
    apiKey?: string
18
  }
19
  tools?: {
20
    enabled?: boolean
21
    customTools?: McpTool[]
22
  }
23
  media?: {
24
    uploadEnabled?: boolean
25
    maxFileSize?: number
26
    allowedTypes?: string[]
27
  }
28
  richtext?: {
29
    enabled?: boolean
30
    processors?: RichtextProcessor[]
31
  }
32
}
typescript
33 lines

Properties

PropertyTypeRequiredDefaultDescription
apiKeystringYes-API key for MCP server authentication
collectionsstring[] | 'all'No'all'Collections to expose via MCP
defaultOperationsobjectNo{ list: true, get: true, create: false, update: false, delete: false }Default operations for collections
serverobjectNo{ port: 3001, host: '0.0.0.0' }MCP server configuration
authobjectNo{ enabled: true }Authentication configuration
toolsobjectNo{ enabled: true }MCP tools configuration
mediaobjectNo{ uploadEnabled: true, maxFileSize: 10485760 }Media upload configuration
richtextobjectNo{ enabled: true }Rich text processing configuration

Collection Configuration

Collection-Specific Options

You can configure individual collections with specific options:

1
collections: [
2
  {
3
    name: 'posts',
4
    mcp: {
5
      operations: {
6
        list: true,
7
        get: true,
8
        create: true,
9
        update: true,
10
        delete: false,
11
      },
12
      fields: ['title', 'content', 'author'],
13
      filters: {
14
        published: true,
15
      },
16
    },
17
  },
18
]
typescript
19 lines

Collection MCP Options

1
interface CollectionMcpOptions {
2
  operations?: {
3
    list?: boolean
4
    get?: boolean
5
    create?: boolean
6
    update?: boolean
7
    delete?: boolean
8
  }
9
  fields?: string[]
10
  filters?: Record<string, any>
11
  relations?: {
12
    populate?: boolean
13
    depth?: number
14
  }
15
}
typescript
16 lines

Global Configuration

Environment Variables

VariableTypeRequiredDefaultDescription
MCP_API_KEYstringYes-API key for MCP server authentication
MCP_AUTH_ENABLEDbooleanNotrueEnable authentication
MCP_MEDIA_UPLOAD_ENABLEDbooleanNotrueEnable media upload
MCP_MEDIA_MAX_FILE_SIZEnumberNo10485760Max file size in bytes

MCP Tools

The plugin automatically generates MCP tools for each collection based on the configured operations.

Generated Tools

For each collection, the following tools are generated:

  • {collection}_list - List documents in a collection
  • {collection}_get - Get a single document by ID
  • {collection}_create - Create a new document (if enabled)
  • {collection}_update - Update an existing document (if enabled)
  • {collection}_delete - Delete a document (if enabled)

Tool Schemas

Each tool includes a comprehensive schema with:

  • Input parameters
  • Output format
  • Error handling
  • Validation rules

Authentication

API Key Authentication

The plugin uses API key authentication by default. Include the API key in the Authorization header:

1
Authorization: Bearer your-api-key-here
bash
2 lines

Disabling Authentication

To disable authentication (not recommended for production):

1
PayloadPluginMcp({
2
  apiKey: process.env.MCP_API_KEY,
3
  auth: {
4
    enabled: false,
5
  },
6
})
typescript
7 lines

API Endpoints

MCP Server Endpoint

The MCP server is available at:

1
http://localhost:3000/api/plugin/mcp
text
2 lines

Available Endpoints

MethodEndpointDescription
GET/api/plugin/mcpGet server information and available tools
POST/api/plugin/mcpExecute MCP tools

Media Upload

Configuration

1
PayloadPluginMcp({
2
  apiKey: process.env.MCP_API_KEY,
3
  media: {
4
    uploadEnabled: true,
5
    maxFileSize: 10485760, // 10MB
6
    allowedTypes: ['image/jpeg', 'image/png', 'image/gif'],
7
  },
8
})
typescript
9 lines

Upload Process

  1. Client sends file to MCP server
  2. Server validates file size and type
  3. File is processed and stored
  4. File ID is returned for use in collections

Rich Text Processing

Configuration

1
PayloadPluginMcp({
2
  apiKey: process.env.MCP_API_KEY,
3
  richtext: {
4
    enabled: true,
5
    processors: ['markdown', 'html'],
6
  },
7
})
typescript
8 lines

Supported Processors

  • Markdown to HTML
  • HTML sanitization
  • Link processing
  • Image optimization

Error Handling

Error Types

Error TypeDescriptionHTTP Status
AuthenticationErrorInvalid or missing API key401
ValidationErrorInvalid input parameters400
NotFoundErrorResource not found404
PermissionErrorInsufficient permissions403
ServerErrorInternal server error500

Error Response Format

1
{
2
  "error": {
3
    "type": "ValidationError",
4
    "message": "Invalid input parameters",
5
    "details": {
6
      "field": "title",
7
      "reason": "required"
8
    }
9
  }
10
}
json
11 lines

Error Handling in Tools

All MCP tools include comprehensive error handling with:

  • Input validation
  • Permission checks
  • Graceful error responses
  • Detailed error messages

Made with ❤️ by

Antler Digital

Modern web applications that are fast, secure, and scalable