Race condition: 'PORT IS IN USE' error caused by Inspector's own process

[btbowman]

Bug Description

When running mcp dev server.py, the Inspector reports PORT IS IN USE at http://localhost:6274 even when the port is confirmed free before launch. The port check appears to run after the Inspector has already bound the port, causing it to detect its own process.

Steps to Reproduce

1. Confirm port 6274 is free: lsof -i :6274 returns nothing
2. Run mcp dev server.py
3. Inspector starts the proxy on port 6277 successfully
4. Inspector then reports port 6274 is in use and fails

Actual Output

⚙️ Proxy server listening on localhost:6277
🔑 Session token: <token>
   Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to disable auth
❌  MCP Inspector PORT IS IN USE at http://localhost:6274 ❌

Expected Behavior

The port availability check should run before binding/starting the server on that port, not after. Currently the startup sequence appears to be:

1. Start proxy server (port 6277) ✅
2. Start Inspector server (binds port 6274)
3. Check if port 6274 is available ← detects its own process, fails ❌

The correct sequence should be:

1. Check if port 6274 is available ✅
2. Check if port 6277 is available ✅
3. Start proxy server (port 6277)
4. Start Inspector server (port 6274)

Root Cause Analysis

This is a race condition. The port availability check (net.createServer or equivalent) runs concurrently with or after the actual server bind. When the check fires, the port is already occupied by the Inspector's own Node.js process.

Additionally, after killing the process with Ctrl+C, the port sometimes remains in CLOSE_WAIT state, requiring kill -9 of the stale Node process to reclaim it. This suggests the graceful shutdown handler may not be properly closing all sockets.

Environment

• MCP SDK: 1.26.0 (Python)
• OS: macOS (Sequoia)
• Python: 3.12
• Node: (used internally by Inspector)

Workarounds

• Use --port flag to specify a different port: mcp dev server.py --port 6280
• Kill stale processes before launch: lsof -ti:6274 | xargs kill -9 2>/dev/null

[btbowman]

Root Cause Analysis & Fix

After reading the source, I found three bugs in client/bin/client.js:

Bug 1: No pre-flight port check

The client calls server.listen(port, host) directly without checking availability first. If a stale process holds the port, the EADDRINUSE error fires — but by then the process is already running.

Bug 2: Missing process.exit(1) in error handler

// BEFORE (line 53-61)
server.on("error", (err) => {
  if (err.message.includes(`EADDRINUSE`)) {
    console.error(`❌  MCP Inspector PORT IS IN USE...`);
  } else {
    throw err;
  }
  // ← No process.exit(1) — process hangs forever
});

Bug 3: No graceful shutdown handler

There are zero SIGINT/SIGTERM handlers and no server.close() call. When the user hits Ctrl+C, the HTTP socket isn't properly closed, leaving the port in CLOSE_WAIT state. The next launch then hits Bug 1.

Fix (applied locally, tested)

import net from "net";

// Pre-flight port check BEFORE binding
function checkPort(targetHost, targetPort) {
  return new Promise((resolve) => {
    const tester = net.createServer();
    tester.once("error", () => resolve(false));
    tester.once("listening", () => {
      tester.close(() => resolve(true));
    });
    tester.listen(targetPort, targetHost);
  });
}

const portFree = await checkPort(host, port);
if (!portFree) {
  console.error(`❌  MCP Inspector PORT IS IN USE at http://${host}:${port} ❌`);
  console.error(`💡 Fix: Run "lsof -ti:${port} | xargs kill -9" or use CLIENT_PORT=<other>`);
  process.exit(1);
}

// ... existing server setup ...

// Add process.exit(1) to the EADDRINUSE handler (defense in depth)
server.on("error", (err) => {
  if (err.message.includes(`EADDRINUSE`)) {
    console.error(`❌  MCP Inspector PORT IS IN USE at http://${host}:${port} ❌`);
  } else {
    throw err;
  }
  process.exit(1);  // ← was missing
});

// Graceful shutdown to release port on Ctrl+C
function shutdown() {
  server.close(() => process.exit(0));
  setTimeout(() => process.exit(0), 3000);
}
process.on("SIGINT", shutdown);
process.on("SIGTERM", shutdown);

The same fixes should also be applied to server/build/index.js (the proxy server). Happy to open a PR if that would be helpful.