The mcpgen CLI suppresses raw Python stack traces for end users. Errors appear as concise, formatted lines. Use these controls for deeper troubleshooting.

Default silent mode

The mcpgen CLI displays error messages when operating in silent mode by default. Silent mode means that raw Python stack traces are suppressed, and errors are shown as concise, user-friendly messages instead of verbose internal details. The following outlines the default error output style for different failure scenarios in mcpgen:
Situation Output style
Unexpected internal exception The CLI displays: Error: Unexpected error: <message> without showing a traceback.
Import or initialization failure The CLI outputs a single-line error message without exposing Python internals.
Unsupported Python version (<3.10) The CLI shows a version guard message instead of a TypeError, indicating that the interpreter is too old.

Python version guard

The mcpgen CLI enforces a minimum Python version requirement to ensure compatibility with modern language features and libraries. The tool requires Python 3.10 or higher. If you attempt to run mcpgen on an older interpreter, the CLI will not proceed and will display a clear error message. For example, when an older Python version is detected, the CLI emits the following message:
Error: Unsupported Python version. Detected 3.9. Required >= 3.10

This message indicates that the current environment does not meet the minimum version requirement.

To fix this issue:
  1. Check your Python version:
    python --version
  2. Upgrade Python to 3.10 or later using your system package manager or official installer.
  3. Validate your environment after upgrading:
    ./mcpgen doctor

    This command confirms that the dependencies meet the required specifications.

Common troubleshooting scenarios

The following table summarizes how to quickly resolve common issues encountered during MCP operations by applying the recommended actions for each scenario:
Scenario Action
Suspect stale wheel code Set the environment variable MCPGEN_FORCE_REFRESH=1 and re-run the desired mcpgen command to force a clean wheel extraction.
Validate environment and versions Run ./mcpgen doctor to check Python version, dependencies, and configuration integrity.
Verify generated configuration quickly Use cat generated/<profile_name>/server/mcp_server_config.json to inspect the generated server configuration file.
Images not found after unpacking Execute ./load_images.sh followed by ./mcpgen list to reload images and confirm availability.

Minimal bug report template

Include the following when filing an issue:
  • Full output from running the ./mcpgen doctor command to help verify environment health and configuration.
  • The exact command you executed, including all flags and parameters, so the issue can be reproduced accurately.
  • Complete error message displayed by the CLI to assist in diagnosing the problem.
  • Python version installed on your system by running python --version.
  • The operating system (OS) and hardware architecture, for example, Ubuntu 22.04 on x86_64 to provide context for environment-specific issues.