Troubleshooting

Common issues and solutions when working with MCP Gateway.

Server won't start

Check the configuration

kp gateway validate

This will show any syntax errors in your .mcp.json.

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

kp status  # Check if gateway is running
kp gateway start  # Start if not running

Port conflict

The gateway defaults to port 8989. If that's in use:

kp gateway start --port 8990

Server crashes

Check server logs

kp logs --server context7

Memory issues

If servers are OOM-killed, check system memory:

kp 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

Getting help