Troubleshooting
Common issues and solutions when working with MCP Gateway.
Server won't start
Check the configuration
manage_config(action="validate")
This returns a validation report for your config.yaml (errors + warnings).
Check environment variables
Ensure all ${VAR} references in your config have corresponding values in your .env file.
get_server_config(server="the-server-name")
Check the command exists
which npx # or "where npx" on Windows
Connection refused
Gateway not running
mcpg status # Check if gateway is running
mcpg start # Start if not running
Port conflict
The gateway defaults to port 8989. If that is in use:
mcpg start --port 8990
Server crashes
Check server logs
mcpg logs
Check health
get_health()
Tools not appearing
Server scope mismatch
If using workspace scope, ensure you’re passing the correct cwd for the workspace context.
Lazy loading
Tools are loaded on-demand. Ask the AI to use a specific tool to trigger loading:
"Use context7 to look up the React docs for useEffect"
Slow startup
First-time npm install
The first time a server runs, npx -y downloads the package. Subsequent starts are faster.
Docker image pull
Docker servers pull images on first run. Pre-pull for faster starts:
docker pull mcp/fetch:latest