Skip to content

Troubleshooting

This guide covers common issues and their solutions when working with the MCP Client module.

Connection Issues

"Could not fetch tools from server"

This error appears when the module cannot connect to or communicate with an MCP server.

For HTTP Transport

Symptoms: - Error when saving MCP server configuration - Tools list is empty - Connection timeout errors

Solutions:

  1. Verify endpoint URL bash curl -X POST https://your-mcp-server.com/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

  2. Check server is running

  3. Verify the MCP server process is running
  4. Check server logs for errors

  5. Ensure server is listening on the correct port

  6. Verify network connectivity

  7. Check firewall rules allow outbound connections
  8. Verify DNS resolves correctly: nslookup your-server.com

  9. Test from the Drupal server: ping your-server.com

  10. Check SSL certificates (for HTTPS)

  11. Verify certificate is valid: curl -vI https://your-server.com
  12. Check certificate is not expired

  13. Ensure certificate chain is complete

  14. Review timeout settings

  15. Increase timeout value if server is slow
  16. Try 60-120 seconds for initial testing

For STDIO Transport

Symptoms: - Error when saving MCP server configuration - Process starts but no tools appear - "Command not found" errors

Solutions:

  1. Test command manually ```bash # Switch to web server user sudo -u www-data bash

# Test the command node /path/to/mcp-server/index.js

# Test with STDIO echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node /path/to/server.js ```

  1. Verify file paths ```bash # Check file exists ls -la /path/to/mcp-server/index.js

# Check execute permissions ls -la $(which node) ```

  1. Check permissions ```bash # Verify ownership ls -la /path/to/mcp-server/

# Fix if needed chown -R www-data:www-data /path/to/mcp-server/ chmod +x /path/to/mcp-server/index.js ```

  1. Review process output
  2. Check Drupal logs: Administration » Reports » Recent log messages
  3. Look for stderr output from the process

  4. Check for missing dependencies

  5. Verify working directory

  6. Ensure working directory exists
  7. Check web server user can access it
  8. Set correct working directory in configuration

Server Status Issues

"MCP server is not enabled"

Problem: Trying to use a disabled MCP server.

Solution:

  1. Navigate to Administration » Configuration » AI » MCP Servers
  2. Find your server in the list
  3. Click "Edit"
  4. Check the "Enabled" checkbox
  5. Click "Save"

Server Appears Enabled But Tools Don't Work

Solutions:

  1. Clear cache bash drush cr

  2. Verify connection

  3. Test in API Explorer
  4. Check recent log messages
  5. Review server logs

Tool Issues

"MCP tool is not enabled"

Problem: Trying to call a disabled tool.

Solution:

  1. Navigate to server configuration
  2. Scroll to "Enabled tools" section
  3. Check the box for the desired tool
  4. Click "Save"

Tools Don't Appear in API Explorer

Symptoms: - MCP server is configured and enabled - Tools list shows tools are enabled - Tools don't appear in API Explorer

Solutions:

  1. Clear cache bash drush cr

  2. Verify server is enabled

  3. Check server status in MCP Server list

  4. Ensure "Enabled" is checked

  5. Check AI module integration

  6. Verify AI module is enabled
  7. Check AI module configuration

  8. Review AI module logs

  9. Refresh plugin cache bash drush cr drush php-eval "\\Drupal::service('plugin.manager.ai.function')->clearCachedDefinitions();"

Tool Execution Fails

Symptoms: - Tool appears in API Explorer - Calling tool returns an error - Error messages in logs

Solutions:

  1. Check parameters
  2. Verify all required parameters are provided
  3. Check parameter types match schema

  4. Review parameter format

  5. Review error messages

  6. Check Drupal logs for detailed errors
  7. Look for MCP server error responses

  8. Review parameter validation errors

  9. Test with minimal parameters

  10. Start with required parameters only
  11. Add optional parameters one at a time

  12. Identify which parameter causes issues

  13. Verify MCP server health

  14. Check server logs
  15. Test tool directly on MCP server
  16. Verify server isn't overloaded

Authentication Issues

Environment Variables Not Working

Symptoms: - MCP server returns authentication errors - API keys seem not to be passed - "Unauthorized" or "403" errors

Solutions:

  1. Verify Key module configuration bash drush config:get key.key.your_key_name

  2. Check key exists and is accessible

  3. Navigate to Administration » Configuration » System » Keys
  4. Verify key exists
  5. Test key value retrieval

  6. Check key permissions

  7. Review environment variable configuration

  8. Edit MCP server configuration
  9. Verify variable names match what server expects
  10. Ensure "Type" is set to "Key" for sensitive values

  11. Confirm correct key is selected

  12. For STDIO: Test environment ```bash # Create test script echo '#!/bin/bash' > /tmp/test-env.sh echo 'env' >> /tmp/test-env.sh chmod +x /tmp/test-env.sh

# Run as web server user sudo -u www-data /tmp/test-env.sh ```

  1. For HTTP: Check headers
  2. Review MCP server logs to see what headers are received
  3. Verify authentication method matches server expectations
  4. Test with curl including headers

Performance Issues

Slow Tool Execution

Symptoms: - Tools take long time to execute - Timeout errors - Agent operations are slow

Solutions:

  1. Increase timeout
  2. Edit MCP server configuration
  3. Increase timeout value (60-120 seconds)

  4. Save and test

  5. Check server performance

  6. Monitor MCP server resource usage
  7. Check for slow database queries

  8. Review server logs for performance issues

  9. Optimize tool calls

  10. Reduce unnecessary tool calls
  11. Cache results when possible

  12. Use batch operations if available

  13. Monitor network latency (HTTP) bash curl -w "@curl-format.txt" -o /dev/null -s https://your-server.com

High Memory Usage

Symptoms: - PHP memory errors - Server running out of memory - Slow performance

Solutions:

  1. Increase PHP memory limit php // In settings.php ini_set('memory_limit', '512M');

  2. Limit concurrent connections

  3. Reduce number of enabled MCP servers
  4. Disable unused tools

  5. Implement queueing for heavy operations

  6. Monitor process memory (STDIO) bash ps aux | grep mcp top -p $(pgrep -f "mcp-server")

Installation Issues

PHP Version Error

Error: "MCP Client requires PHP 8.2 or higher"

Solution:

Upgrade PHP to version 8.2 or higher:

# Check current version
php -v

# Ubuntu/Debian
sudo apt-get install php8.2

# Update Drupal to use new PHP version
# (varies by web server configuration)

Composer Installation Fails

Solutions:

  1. Memory issues bash COMPOSER_MEMORY_LIMIT=-1 composer require drupal/mcp_client

  2. Dependency conflicts bash composer require drupal/mcp_client --with-dependencies composer update --with-dependencies

  3. Clear Composer cache bash composer clear-cache composer require drupal/mcp_client

Debugging

Enable Debug Logging

  1. Enable Drupal logging php // In settings.php $config['system.logging']['error_level'] = 'verbose';

  2. Watch logs bash drush watchdog:tail # or tail -f /path/to/drupal/sites/default/files/logs/drupal.log

  3. For STDIO processes

  4. Add DEBUG environment variable
  5. Review process output in logs
  6. Use process monitoring tools

Testing Checklist

When troubleshooting, work through this checklist:

  • [ ] Module is installed and enabled
  • [ ] Dependencies are met (PHP version, required modules)
  • [ ] MCP server configuration is saved
  • [ ] MCP server is enabled
  • [ ] Connection test succeeds (manual curl/command test)
  • [ ] Tools are discovered and listed
  • [ ] Desired tools are enabled
  • [ ] Environment variables are configured (if needed)
  • [ ] Keys are created and accessible (if needed)
  • [ ] Cache is cleared
  • [ ] Logs show no errors
  • [ ] Test in API Explorer works

Getting Help

If you're still experiencing issues:

  1. Check issue queue
  2. Visit https://www.drupal.org/project/issues/mcp_client
  3. Search for similar issues

  4. Review open and closed issues

  5. Gather information

  6. PHP version: php -v
  7. Drupal version: drush status
  8. Module version: drush pm:list | grep mcp_client
  9. Error messages from logs

  10. Steps to reproduce

  11. Create issue

  12. Provide detailed information
  13. Include error messages
  14. Describe expected vs actual behavior

  15. List troubleshooting steps tried

  16. Community support

  17. Drupal Slack: #ai channel
  18. Stack Exchange: drupal.stackexchange.com
  19. Drupal forums

Next Steps