Troubleshooting

Server Not Starting

If the MCP server doesn't start:

1. Check PHP version (requires 8.2+):

   1

   $ php --version

2. Verify the binary exists:

   1

   $ ls -la vendor/bin/mate

3. Run manually to see errors:

   1

   $ vendor/bin/mate serve

   Look for error messages in the output.

4. Check for missing dependencies:

   1

   $ composer install

Server Crashes on Startup

If the server starts but immediately crashes:

1. Check for syntax errors in your custom tools:

   1

   $ php -l mate/MyTool.php

2. Verify service configuration:

   1

   $ php -r "require 'vendor/autoload.php'; include '.mate/services.php';"

3. Check for circular dependencies in your service configuration.

Permission Denied Errors

If you get permission errors:

1

$ chmod +x vendor/bin/mate

On Windows, ensure PHP is in your PATH and run:

1

> php vendor/bin/mate serve

Enable Debug Logging

Set the MATE_DEBUG environment variable to enable debug-level logging:

1

$ MATE_DEBUG=1 vendor/bin/mate serve

This outputs detailed debug information to stderr, including:

• Service registration details
• Extension discovery information
• Tool execution logs
• Internal state changes

Log to File

Set the MATE_DEBUG_FILE environment variable to redirect logs to a file:

1

$ MATE_DEBUG_FILE=1 vendor/bin/mate serve

This creates a dev.log file in the current directory with all log output. This is particularly useful when running the server through AI assistants (like Claude Code) where stderr output may not be easily accessible.

To customize the log file path, use the MATE_DEBUG_LOG_FILE environment variable:

1

$ MATE_DEBUG_FILE=1 MATE_DEBUG_LOG_FILE=/var/log/mate/debug.log vendor/bin/mate serve

You can combine both environment variables for debug logging to file:

1

$ MATE_DEBUG=1 MATE_DEBUG_FILE=1 vendor/bin/mate serve

For AI assistant integration (e.g., Claude Code MCP configuration), add these to the server configuration:

1
2
3
4
5
6
7
8
9
10
11
12

{
    "mcpServers": {
        "symfony-ai-mate": {
            "command": "php",
            "args": ["vendor/bin/mate", "serve"],
            "env": {
                "MATE_DEBUG": "1",
                "MATE_DEBUG_FILE": "1"
            }
        }
    }
}

Test Tools Manually

Create a simple test script:

1
2
3
4
5

// test-tool.php
require 'vendor/autoload.php';

$tool = new App\Mate\MyTool();
var_dump($tool->execute('test-param'));

Clear Cache

If you're experiencing stale behavior:

1

$ vendor/bin/mate clear-cache