← Back to Documentation

API Reference

Table of Contents

Plugin Configuration

PayloadPluginMcp

The main plugin function that returns a PayloadCMS plugin configuration.

function PayloadPluginMcp(pluginOptions: PayloadPluginMcpConfig): (config: Config) => Config

Parameters

  • pluginOptions - Configuration object for the plugin

Returns

A function that takes a PayloadCMS config and returns the modified config with the plugin installed.

Example

import { buildConfig } from 'payload'
import { PayloadPluginMcp } from 'payload-plugin-mcp'

export default buildConfig({
  plugins: [
    PayloadPluginMcp({
      apiKey: process.env.MCP_API_KEY,
      collections: 'all',
      defaultOperations: {
        list: true,
        get: true,
        create: false,
        update: false,
        delete: false,
      },
    }),
  ],
})

Collection Configuration

Collection Options

Configure which collections to expose and their operations:

collections: 'all' | string[] | CollectionConfig[]

Options

  • 'all' - Expose all collections with default operations
  • string[] - Array of collection names to expose
  • CollectionConfig[] - Detailed configuration for each collection

CollectionConfig Interface

interface CollectionConfig {
  collection: Collection
  options?: {
    operations?: {
      list?: boolean
      get?: boolean
      create?: boolean
      update?: boolean
      delete?: boolean
    }
    toolPrefix?: string
    description?: string
    excludeFields?: string[]
  }
}

Global Configuration

PayloadPluginMcpConfig Interface

interface PayloadPluginMcpConfig {
  apiKey: string
  collections: 'all' | CollectionConfig[]
  defaultOperations?: {
    list?: boolean
    get?: boolean
    create?: boolean
    update?: boolean
    delete?: boolean
  }
  serverPort?: number
  serverHost?: string
  serverName?: string
  serverDescription?: string
  enableHttpTransport?: boolean
  enableStdioTransport?: boolean
  disabled?: boolean
  debug?: boolean
}

MCP Tools

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

Generated Tools

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

Tool Schema

Each tool includes a JSON schema generated from the collection's field definitions, ensuring type safety and validation.

Authentication

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

Authorization: Bearer your-api-key-here

Alternatively, you can pass the API key as a query parameter:

?api_key=your-api-key-here

API Endpoints

The plugin creates the following endpoints:

  • GET /api/plugin/mcp - Discovery endpoint (lists available tools)
  • POST /api/plugin/mcp - JSON-RPC 2.0 endpoint for MCP protocol
  • OPTIONS /api/plugin/mcp - CORS preflight handling

Testing Endpoints

Discovery

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

Tool Invocation

curl -X POST \ -H "Authorization: Bearer your-api-key" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "posts_list", "arguments": { "limit": 5 } } }' \ http://localhost:3000/api/plugin/mcp

Media Upload

Media uploads are handled automatically through PayloadCMS's built-in media handling. The plugin exposes media collections with appropriate MCP tools for:

  • Listing media files
  • Getting media file details
  • Uploading new media files
  • Updating media metadata
  • Deleting media files

Rich Text Processing

Rich text fields are automatically processed to extract plain text content for AI consumption while preserving the original rich text structure for display.

Error Handling

The plugin includes comprehensive error handling with standardized error responses:

interface McpError {
  error: {
    code: string
    message: string
    details?: any
  }
}

Common Error Codes

  • AUTHENTICATION_FAILED - Invalid or missing API key
  • COLLECTION_NOT_FOUND - Collection doesn't exist
  • DOCUMENT_NOT_FOUND - Document doesn't exist
  • VALIDATION_ERROR - Invalid input data
  • PERMISSION_DENIED - Operation not allowed