When it doesn't connect
Hammer icon doesn't appear in Claude Desktop
Check your JSON config is valid — a missing comma or bracket will silently break it. Paste your config into jsonlint.com to verify.
Server listed but tools don't work
Check the MCP logs:
# Mac
tail -f ~/Library/Logs/Claude/mcp*.log
# Windows
Get-Content "$env:APPDATA\Claude\logs\mcp*.log" -Wait
The logs show exactly what Claude Desktop sees when starting your server and what errors occurred.
"Cannot find module" error in logs
Your path is wrong. Make sure you're pointing at the built build/index.js, not src/index.ts. And use the full absolute path, not a relative one.
Tools call but return errors
Add more error logging to your handlers using console.error(). Remember — console.log() breaks stdio, console.error() is safe.
Test without Claude Desktop
You can test your server in isolation using the MCP Inspector — saves a lot of restart cycles:
npx @modelcontextprotocol/inspector node build/index.js
This opens a browser UI where you can call your tools directly and see the raw input/output without needing Claude Desktop in the loop.
What to build next
You have a working, multi-tool MCP server. From here:
Add more tools to this server. Database queries, API calls, file writes, running shell commands. Each one follows the same server.tool() pattern.
Try remote transport. Once your server is stable locally, you can deploy it remotely using Streamable HTTP transport so teammates can connect without running the server themselves.
Explore Resources. If you have data Claude should be able to read passively (documentation, config files, reference data) rather than explicitly call as a tool, Resources are cleaner than Tools for that use case.
Publish to the MCP registry. If your server is useful enough to share, the MCP registry at mcpservers.org is where people find community servers.