MCP servers can fail silently. Here’s how to debug the most common issues.

Problem 1: Server not connecting

Symptom: Host doesn’t show your tools.

Fix: Check the server command works standalone:

node /path/to/server.js  # Should start without errors

Common causes: wrong path, missing dependencies, Node version mismatch.

Problem 2: Tools not appearing

Symptom: Server connects but tools don’t show up.

Fix: Verify tools are registered before server.connect():

server.tool('my_tool', schema, handler);  // Must be before connect
await server.connect(transport);

Problem 3: Tool calls failing

Symptom: Tool appears but returns errors.

Fix: Add logging to your handler:

server.tool('my_tool', schema, async (params) => {
  console.error('Tool called with:', JSON.stringify(params));
  try {
    const result = await doWork(params);
    return { content: [{ type: 'text', text: result }] };
  } catch (e) {
    console.error('Error:', e);
    return { content: [{ type: 'text', text: e.message }], isError: true };
  }
});

stderr output goes to the host’s logs (check Claude Code terminal or Cursor output panel).

Problem 4: Environment variables missing

Symptom: Auth failures, API errors.

Fix: Pass env vars in the host config:

{"env": {"API_KEY": "sk-...", "DB_URL": "postgresql://..."}}

Problem 5: Timeout on long operations

Symptom: Tool call hangs then fails.

Fix: Add timeouts and progress reporting. MCP supports progress notifications for long-running operations.

General tips

1. Always log to stderr (stdout is reserved for MCP protocol)
2. Test your server with the MCP Inspector tool
3. Start simple — one tool, verify it works, then add more
4. Check our MCP Security Checklist if auth-related

Related: MCP Complete Guide · Build MCP Server (TypeScript) · Build MCP Server (Python)