Debug a Server That Won't Start
Read logs and fix common startup failures.
Debug a Server That Won't Start is a free MCP Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the MCP Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
When Nothing Shows Up
Sometimes you restart the host and your tools simply aren’t there. Don’t panic: startup failures follow a few predictable patterns. 🛠️
Find the Logs First
Your first move is always the logs. Claude Desktop writes per-server log files that capture exactly why a process refused to start.
~/Library/Logs/Claude/mcp-server-NAME.logWrong Command or Path
The top cause is a bad command or a relative script path. The host can’t find python or your file, so the process never even runs.
Test It in Your Terminal
Run the exact command from your config by hand. If it crashes in your terminal, it will crash for the host too, and the error is right there.
python /abs/path/server.pyMissing Dependencies
An ImportError means the host launched a Python without your packages. Pin the interpreter or use uv so the right environment is used.
Stray stdout Output
A sneaky one: any print to stdout corrupts the handshake, so the client gives up. Move every print over to stderr and try again.
Bad JSON in the Config
A single trailing comma makes claude_desktop_config.json invalid, and the host loads no servers at all. Validate the file when in doubt.
Forgot to Restart
The simplest miss: you edited config but never restarted. Quit Claude completely, not just close the window, then open it fresh.
Isolate with the Inspector
Still stuck? Launch the server in the Inspector. If it works there but not in the host, the problem is your config, not your code.
mcp dev server.pyRead the Actual Error
Resist guessing. The traceback in your stderr names the exact line and exception. Read it fully before changing anything. 📋
Change One Thing
When you do edit, change a single thing, then retest. Tweaking three settings at once hides which fix actually solved the problem.
Quick Check
A server runs fine in the MCP Inspector but never appears in Claude Desktop. What does that point to?
Recap
You learned to read logs, test the command directly, fix paths, deps, and stray prints, and isolate with the Inspector. Your server is verified! 🎉
Frequently asked questions
Is the “Debug a Server That Won't Start” lesson free?
Yes — the full text of “Debug a Server That Won't Start” is free to read here on the web, and the MCP Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the MCP Academy course, upgrade to CoddyKit PRO.
What will I learn in “Debug a Server That Won't Start”?
Read logs and fix common startup failures. You practise MCP Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start MCP Academy?
No prior experience is required. MCP Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Debug a Server That Won't Start” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this MCP Academy lesson?
Yes. Every MCP Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- How stdio Transport Works
- Wire It into Claude Desktop
- Explore with MCP Inspector
- Debug a Server That Won't Start