From 2a2f4c8e4d5f98796703ddede3ba3afdabd3d34d Mon Sep 17 00:00:00 2001
From: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>
Date: Fri, 27 Mar 2026 14:31:08 -0400
Subject: [PATCH] Clean error when dev apps ports are in use (#3658)

---
 src/fastmcp/cli/apps_dev.py | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/src/fastmcp/cli/apps_dev.py b/src/fastmcp/cli/apps_dev.py
index 9c3b9197a..d1e2be811 100644
--- a/src/fastmcp/cli/apps_dev.py
+++ b/src/fastmcp/cli/apps_dev.py
@@ -1630,6 +1630,29 @@ async def run_dev_apps(
     async def _body() -> None:
         nonlocal user_proc
 
+        # Check ports before starting anything
+        import socket
+
+        for port, label in [(mcp_port, "MCP server"), (dev_port, "dev UI")]:
+            in_use = False
+            for family, addr in (
+                (socket.AF_INET, ("127.0.0.1", port)),
+                (socket.AF_INET6, ("::1", port, 0, 0)),
+            ):
+                try:
+                    with socket.socket(family, socket.SOCK_STREAM) as s:
+                        if s.connect_ex(addr) == 0:
+                            in_use = True
+                            break
+                except OSError:
+                    continue
+            if in_use:
+                logger.error(
+                    f"Port {port} ({label}) is already in use. "
+                    f"Try --mcp-port or --dev-port to use different ports."
+                )
+                sys.exit(1)
+
         logger.info(f"Starting user server on port {mcp_port}…")
         logger.info("Fetching app-bridge.js from npm…")