Documentation

PayloadCMS MCP Plugin

External Links

GitHub RepositoryNPM Package
Theme

Troubleshooting Guide

This guide helps you resolve common issues when using the PayloadCMS MCP Integration Plugin.

Table of Contents

Common Issues

Plugin Not Loading

Symptoms:

  • No MCP server output in console
  • Plugin appears to be ignored

Solutions:

  1. Check PayloadCMS version compatibility:

    1
    npm list payload
    bash
    2 lines

    Ensure you're using PayloadCMS 3.0.0 or higher.

  2. Verify plugin installation:

    1
    npm list payload-plugin-mcp
    bash
    2 lines

  3. Check configuration syntax:

    1
    // Ensure proper import and usage
    2
    import { PayloadPluginMcp } from 'payload-plugin-mcp'
    3
    

    4
    export default buildConfig({
    5
      plugins: [
    6
        PayloadPluginMcp({
    7
          apiKey: process.env.MCP_API_KEY,
    8
          collections: 'all',
    9
        }),
    10
      ],
    11
    })
    typescript
    12 lines

Server Not Starting

Symptoms:

  • MCP server fails to start
  • Port already in use errors

Solutions:

  1. Check port availability:

    1
    lsof -i :3001
    bash
    2 lines

  2. Change server port:

    1
    PayloadPluginMcp({
    2
      apiKey: process.env.MCP_API_KEY,
    3
      server: {
    4
        port: 3002,
    5
      },
    6
    })
    typescript
    7 lines

  3. Check environment variables:

    1
    echo $MCP_API_KEY
    bash
    2 lines

Authentication Problems

Invalid API Key

Symptoms:

  • 401 Unauthorized errors
  • Authentication failed messages

Solutions:

  1. Verify API key format:

    1
    # Generate a new secure key
    2
    openssl rand -hex 32
    bash
    3 lines

  2. Check environment variable:

    1
    # In your .env file
    2
    MCP_API_KEY=your-secret-api-key-here
    bash
    3 lines

  3. Restart the server after changing environment variables

Missing Authorization Header

Symptoms:

  • 401 Unauthorized errors
  • "Authorization header required" messages

Solutions:

  1. Include Authorization header in requests:

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

  2. Check MCP client configuration:

    1
    // Ensure proper header configuration
    2
    const headers = {
    3
      Authorization: `Bearer ${process.env.MCP_API_KEY}`,
    4
      'Content-Type': 'application/json',
    5
    }
    typescript
    6 lines

Collection Issues

Collections Not Exposed

Symptoms:

  • Collections not appearing in MCP tools
  • "Collection not found" errors

Solutions:

  1. Check collection configuration:

    1
    PayloadPluginMcp({
    2
      apiKey: process.env.MCP_API_KEY,
    3
      collections: ['posts', 'users'], // Explicit list
    4
    })
    typescript
    5 lines

  2. Verify collection names:

    1
    // Ensure collection names match exactly
    2
    collections: [
    3
      {
    4
        name: 'posts', // Must match collection name
    5
        slug: 'posts',
    6
      },
    7
    ]
    typescript
    8 lines

  3. Check collection permissions:

    1
    // Ensure collections have proper access control
    2
    collections: [
    3
      {
    4
        name: 'posts',
    5
        access: {
    6
          read: () => true,
    7
          create: () => true,
    8
        },
    9
      },
    10
    ]
    typescript
    11 lines

Field Access Issues

Symptoms:

  • Fields not appearing in responses
  • "Field not found" errors

Solutions:

  1. Check field configuration:

    1
    PayloadPluginMcp({
    2
      apiKey: process.env.MCP_API_KEY,
    3
      collections: [
    4
        {
    5
          name: 'posts',
    6
          mcp: {
    7
            fields: ['title', 'content', 'author'], // Explicit field list
    8
          },
    9
        },
    10
      ],
    11
    })
    typescript
    12 lines

  2. Verify field names:

    1
    // Ensure field names match collection schema
    2
    fields: [
    3
      {
    4
        name: 'title',
    5
        type: 'text',
    6
      },
    7
    ]
    typescript
    8 lines

Server Configuration

Port Conflicts

Symptoms:

  • "Port already in use" errors
  • Server fails to bind to port

Solutions:

  1. Find and kill process using port:

    1
    lsof -ti:3001 | xargs kill -9
    bash
    2 lines

  2. Use different port:

    1
    PayloadPluginMcp({
    2
      apiKey: process.env.MCP_API_KEY,
    3
      server: {
    4
        port: 3002,
    5
        host: '0.0.0.0',
    6
      },
    7
    })
    typescript
    8 lines

  3. Check for other services:

    1
    netstat -tulpn | grep :3001
    bash
    2 lines

Host Binding Issues

Symptoms:

  • Server not accessible from external clients
  • Connection refused errors

Solutions:

  1. Check host configuration:

    1
    PayloadPluginMcp({
    2
      apiKey: process.env.MCP_API_KEY,
    3
      server: {
    4
        host: '0.0.0.0', // Bind to all interfaces
    5
      },
    6
    })
    typescript
    7 lines

  2. Check firewall settings:

    1
    # Ubuntu/Debian
    2
    sudo ufw allow 3001
    3
    

    4
    # CentOS/RHEL
    5
    sudo firewall-cmd --add-port=3001/tcp --permanent
    6
    sudo firewall-cmd --reload
    bash
    7 lines

Media Upload Issues

File Size Limits

Symptoms:

  • "File too large" errors
  • Upload failures

Solutions:

  1. Increase file size limit:

    1
    PayloadPluginMcp({
    2
      apiKey: process.env.MCP_API_KEY,
    3
      media: {
    4
        maxFileSize: 52428800, // 50MB
    5
      },
    6
    })
    typescript
    7 lines

  2. Check server limits:

    1
    // Next.js configuration
    2
    const nextConfig = {
    3
      experimental: {
    4
        serverComponentsExternalPackages: ['sharp'],
    5
      },
    6
    }
    typescript
    7 lines

File Type Restrictions

Symptoms:

  • "File type not allowed" errors
  • Upload rejected

Solutions:

  1. Configure allowed types:

    1
    PayloadPluginMcp({
    2
      apiKey: process.env.MCP_API_KEY,
    3
      media: {
    4
        allowedTypes: ['image/jpeg', 'image/png', 'image/gif', 'application/pdf'],
    5
      },
    6
    })
    typescript
    7 lines

  2. Check MIME type detection:

    1
    file --mime-type your-file.jpg
    bash
    2 lines

Performance Issues

Slow Response Times

Symptoms:

  • Long response times
  • Timeout errors

Solutions:

  1. Enable caching:

    1
    PayloadPluginMcp({
    2
      apiKey: process.env.MCP_API_KEY,
    3
      cache: {
    4
        enabled: true,
    5
        ttl: 300, // 5 minutes
    6
      },
    7
    })
    typescript
    8 lines

  2. Optimize database queries:

    1
    // Use select to limit fields
    2
    collections: [
    3
      {
    4
        name: 'posts',
    5
        mcp: {
    6
          fields: ['title', 'slug', 'publishedAt'],
    7
        },
    8
      },
    9
    ]
    typescript
    10 lines

  3. Check database indexes:

    1
    // Ensure proper indexing
    2
    collections: [
    3
      {
    4
        name: 'posts',
    5
        fields: [
    6
          {
    7
            name: 'title',
    8
            type: 'text',
    9
            index: true,
    10
          },
    11
        ],
    12
      },
    13
    ]
    typescript
    14 lines

Memory Usage

Symptoms:

  • High memory consumption
  • Out of memory errors

Solutions:

  1. Limit result sets:

    1
    PayloadPluginMcp({
    2
      apiKey: process.env.MCP_API_KEY,
    3
      pagination: {
    4
        defaultLimit: 10,
    5
        maxLimit: 100,
    6
      },
    7
    })
    typescript
    8 lines

  2. Enable streaming for large datasets:

    1
    PayloadPluginMcp({
    2
      apiKey: process.env.MCP_API_KEY,
    3
      streaming: {
    4
        enabled: true,
    5
        chunkSize: 1000,
    6
      },
    7
    })
    typescript
    8 lines

Debugging

Enable Debug Logging

1
PayloadPluginMcp({
2
  apiKey: process.env.MCP_API_KEY,
3
  debug: true,
4
  logging: {
5
    level: 'debug',
6
    format: 'json',
7
  },
8
})
typescript
9 lines

Check Server Logs

1
# Enable verbose logging
2
DEBUG=payload-plugin-mcp:* npm run dev
bash
3 lines

Test MCP Connection

1
# Test basic connectivity
2
curl -v http://localhost:3000/api/plugin/mcp
3


4
# Test with authentication
5
curl -H "Authorization: Bearer your-api-key" \
6
     -H "Content-Type: application/json" \
7
     http://localhost:3000/api/plugin/mcp
bash
8 lines

Use MCP Inspector

1
# Install and run MCP Inspector
2
npx @modelcontextprotocol/inspector http://localhost:3000/api/plugin/mcp
bash
3 lines

Common Debug Commands

1
# Check if server is running
2
ps aux | grep node
3


4
# Check port usage
5
netstat -tulpn | grep :3000
6


7
# Check environment variables
8
env | grep MCP
9


10
# Test API endpoint
11
curl -I http://localhost:3000/api/plugin/mcp
bash
12 lines

Getting Help

If you're still experiencing issues:

  1. Check the logs for detailed error messages
  2. Verify your configuration against the examples
  3. Test with minimal configuration to isolate the issue
  4. Check GitHub issues for similar problems
  5. Create a new issue with detailed information about your setup

Useful Resources

Made with ❤️ by

Antler Digital

Modern web applications that are fast, secure, and scalable