Troubleshooting
Common issues and solutions when working with MCP Gateway.
Server won't start
Check the configuration
mcpg validate
This will show any syntax errors in your config.
Check environment variables
Ensure all ${VAR} references in your config have corresponding values in your .env file.
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 --server context7
Memory issues
If servers are OOM-killed, check system memory:
mcpg status --memory
Tools not appearing
Server scope mismatch
If using workspace scope, ensure your terminal is in the correct project directory.
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