← Back to Documentation

Troubleshooting Guide

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

Table of Contents

Common Issues

1. Plugin Not Loading

Symptoms: Plugin doesn't appear in admin, MCP endpoint not accessible

Possible Causes:

  • Plugin not properly imported in payload.config.ts
  • Syntax errors in configuration
  • Missing dependencies

Solutions:

// Ensure proper import
import { PayloadPluginMcp } from 'payload-plugin-mcp'

// Check plugin configuration
export default buildConfig({
  plugins: [
    PayloadPluginMcp({
      apiKey: process.env.MCP_API_KEY,
      collections: 'all',
    }),
  ],
})

Verification:

  • Check browser console for errors
  • Verify plugin appears in PayloadCMS admin
  • Test MCP endpoint at /api/plugin/mcp

2. MCP Endpoint Not Responding

Symptoms: HTTP 404 or connection refused when accessing MCP endpoint

Solutions:

  • Verify the plugin is properly configured
  • Check that the server is running on the correct port
  • Ensure the endpoint path is correct: /api/plugin/mcp

3. Collections Not Appearing

Symptoms: No collections available in MCP tools

Solutions:

  • Check collection configuration in plugin options
  • Verify collections are properly defined in PayloadCMS
  • Ensure collections have the required fields

Authentication Problems

1. Invalid API Key

Symptoms: HTTP 401 Unauthorized responses

Solutions:

  • Verify MCP_API_KEY environment variable is set
  • Check that the API key matches what's configured in the plugin
  • Ensure the API key is included in the Authorization header

2. Missing Authorization Header

Symptoms: HTTP 401 Unauthorized responses

Solutions:

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

Collection Issues

1. Collection Not Found

Symptoms: Error when trying to access collection tools

Solutions:

  • Verify collection name is correct
  • Check that collection is included in plugin configuration
  • Ensure collection is properly defined in PayloadCMS

2. Field Validation Errors

Symptoms: Validation errors when creating/updating documents

Solutions:

  • Check field requirements in collection schema
  • Verify data types match field definitions
  • Ensure required fields are provided

MCP Protocol Errors

1. Invalid Tool Request

Symptoms: MCP protocol errors in Claude Desktop

Solutions:

  • Verify tool names match generated tools
  • Check parameter schemas match expected format
  • Ensure proper MCP protocol compliance

2. Tool Execution Errors

Symptoms: Tools fail to execute or return errors

Solutions:

  • Check server logs for detailed error messages
  • Verify collection permissions
  • Ensure database connection is working

3. MCP Inspector Connection Issues

Symptoms: Can't connect to MCP server using the inspector

Solutions:

  • Use the correct endpoint: http://localhost:3000/api/plugin/mcp
  • Ensure the server is running before starting the inspector
  • Check that the Authorization header is properly formatted
  • Verify there are no CORS issues
npx @modelcontextprotocol/inspector http://localhost:3000/api/plugin/mcp

Performance Issues

1. Slow Response Times

Symptoms: MCP tools take too long to respond

Solutions:

  • Check database query performance
  • Consider adding database indexes
  • Limit the number of documents returned in list operations
  • Use pagination for large datasets

2. Memory Issues

Symptoms: High memory usage or out of memory errors

Solutions:

  • Limit the number of collections exposed
  • Use pagination for large datasets
  • Consider disabling operations that aren't needed

Deployment Issues

1. Vercel Deployment

Symptoms: Plugin not working in production

Solutions:

  • Ensure environment variables are set in Vercel
  • Check that the plugin is included in the build
  • Verify the API route is properly configured
  • Use the correct production endpoint: /api/plugin/mcp

2. Environment Variables

Symptoms: Configuration not working in production

Solutions:

  • Set all required environment variables in your deployment platform
  • Verify variable names match exactly
  • Check that sensitive values are properly secured

Debug Mode

Enable debug mode to get more detailed logging:

// Add to your payload.config.ts
PayloadPluginMcp({
  apiKey: process.env.MCP_API_KEY,
  collections: 'all',
  debug: true, // Enable debug logging
})

This will provide detailed logs about:

  • Plugin initialization
  • Collection processing
  • Tool generation
  • Request/response details

Getting Help

If you're still experiencing issues:

  • Check the GitHub Issues for similar problems
  • Create a new issue with detailed information about your setup
  • Include relevant logs and configuration details
  • Provide steps to reproduce the issue

Pro Tip: When reporting issues, include your PayloadCMS version, Node.js version, and a minimal reproduction case.