fix(e2e): use factory pattern for MCP servers to support parallel connections

McpServer only supports one transport at a time. When multiple browser
contexts connected in parallel, calling server.connect(transport) for
each session overwrote the previous transport's callbacks, causing
connection corruption and test timeouts.

Changes:
- server-utils.ts: accept factory function instead of single instance
- All 9 example servers: wrap server creation in createServer() function
- playwright.config.ts: re-enable parallel execution (4 workers)
- servers.spec.ts: add toBeEnabled wait for server connection
- Update screenshot baselines for basic-vanillajs and cohort-heatmap

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: ochafik

examples/basic-server-react/server.ts

@@ -7,25 +7,28 @@ import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
+const RESOURCE_URI = "ui://get-time/mcp-app.html";
 
-const server = new McpServer({
-  name: "Basic MCP App Server (React-based)",
-  version: "1.0.0",
-});
-
-// MCP Apps require two-part registration: a tool (what the LLM calls) and a
-// resource (the UI it renders). The `_meta` field on the tool links to the
-// resource URI, telling hosts which UI to display when the tool executes.
-{
-  const resourceUri = "ui://get-time/mcp-app.html";
+/**
+ * Creates a new MCP server instance with tools and resources registered.
+ * Each HTTP session needs its own server instance because McpServer only supports one transport.
+ */
+function createServer(): McpServer {
+  const server = new McpServer({
+    name: "Basic MCP App Server (React-based)",
+    version: "1.0.0",
+  });
 
+  // MCP Apps require two-part registration: a tool (what the LLM calls) and a
+  // resource (the UI it renders). The `_meta` field on the tool links to the
+  // resource URI, telling hosts which UI to display when the tool executes.
   server.registerTool(
     "get-time",
     {
       title: "Get Time",
       description: "Returns the current server time as an ISO 8601 string.",
       inputSchema: {},
-      _meta: { [RESOURCE_URI_META_KEY]: resourceUri },
+      _meta: { [RESOURCE_URI_META_KEY]: RESOURCE_URI },
     },
     async (): Promise<CallToolResult> => {
       const time = new Date().toISOString();
@@ -36,8 +39,8 @@ const server = new McpServer({
   );
 
   server.registerResource(
-    resourceUri,
-    resourceUri,
+    RESOURCE_URI,
+    RESOURCE_URI,
     {},
     async (): Promise<ReadResourceResult> => {
       const html = await fs.readFile(path.join(DIST_DIR, "mcp-app.html"), "utf-8");
@@ -46,19 +49,21 @@ const server = new McpServer({
         contents: [
           // Per the MCP App specification, "text/html;profile=mcp-app" signals
           // to the Host that this resource is indeed for an MCP App UI.
-          { uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html },
+          { uri: RESOURCE_URI, mimeType: RESOURCE_MIME_TYPE, text: html },
         ],
       };
     },
   );
+
+  return server;
 }
 
 async function main() {
   if (process.argv.includes("--stdio")) {
-    await server.connect(new StdioServerTransport());
+    await createServer().connect(new StdioServerTransport());
   } else {
     const port = parseInt(process.env.PORT ?? "3101", 10);
-    await startServer(server, { port, name: "Basic MCP App Server (React-based)" });
+    await startServer(createServer, { port, name: "Basic MCP App Server (React-based)" });
   }
 }
 

examples/basic-server-vanillajs/server.ts

@@ -7,25 +7,28 @@ import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
+const RESOURCE_URI = "ui://get-time/mcp-app.html";
 
-const server = new McpServer({
-  name: "Basic MCP App Server (Vanilla JS)",
-  version: "1.0.0",
-});
-
-// MCP Apps require two-part registration: a tool (what the LLM calls) and a
-// resource (the UI it renders). The `_meta` field on the tool links to the
-// resource URI, telling hosts which UI to display when the tool executes.
-{
-  const resourceUri = "ui://get-time/mcp-app.html";
+/**
+ * Creates a new MCP server instance with tools and resources registered.
+ * Each HTTP session needs its own server instance because McpServer only supports one transport.
+ */
+function createServer(): McpServer {
+  const server = new McpServer({
+    name: "Basic MCP App Server (Vanilla JS)",
+    version: "1.0.0",
+  });
 
+  // MCP Apps require two-part registration: a tool (what the LLM calls) and a
+  // resource (the UI it renders). The `_meta` field on the tool links to the
+  // resource URI, telling hosts which UI to display when the tool executes.
   server.registerTool(
     "get-time",
     {
       title: "Get Time",
       description: "Returns the current server time as an ISO 8601 string.",
       inputSchema: {},
-      _meta: { [RESOURCE_URI_META_KEY]: resourceUri },
+      _meta: { [RESOURCE_URI_META_KEY]: RESOURCE_URI },
     },
     async (): Promise<CallToolResult> => {
       const time = new Date().toISOString();
@@ -36,8 +39,8 @@ const server = new McpServer({
   );
 
   server.registerResource(
-    resourceUri,
-    resourceUri,
+    RESOURCE_URI,
+    RESOURCE_URI,
     {},
     async (): Promise<ReadResourceResult> => {
       const html = await fs.readFile(path.join(DIST_DIR, "mcp-app.html"), "utf-8");
@@ -46,19 +49,21 @@ const server = new McpServer({
         contents: [
           // Per the MCP App specification, "text/html;profile=mcp-app" signals
           // to the Host that this resource is indeed for an MCP App UI.
-          { uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html },
+          { uri: RESOURCE_URI, mimeType: RESOURCE_MIME_TYPE, text: html },
         ],
       };
     },
   );
+
+  return server;
 }
 
 async function main() {
   if (process.argv.includes("--stdio")) {
-    await server.connect(new StdioServerTransport());
+    await createServer().connect(new StdioServerTransport());
   } else {
     const port = parseInt(process.env.PORT ?? "3102", 10);
-    await startServer(server, { port, name: "Basic MCP App Server (Vanilla JS)" });
+    await startServer(createServer, { port, name: "Basic MCP App Server (Vanilla JS)" });
   }
 }
 

examples/budget-allocator-server/server.ts

@@ -223,82 +223,90 @@ function generateHistory(
 // MCP Server Setup
 // ---------------------------------------------------------------------------
 
-const server = new McpServer({
-  name: "Budget Allocator Server",
-  version: "1.0.0",
-});
-
 const resourceUri = "ui://budget-allocator/mcp-app.html";
 
-server.registerTool(
-  "get-budget-data",
-  {
-    title: "Get Budget Data",
-    description:
-      "Returns budget configuration with 24 months of historical allocations and industry benchmarks by company stage",
-    inputSchema: {},
-    _meta: { [RESOURCE_URI_META_KEY]: resourceUri },
-  },
-  async (): Promise<CallToolResult> => {
-    const response: BudgetDataResponse = {
-      config: {
-        categories: CATEGORIES.map(({ id, name, color, defaultPercent }) => ({
-          id,
-          name,
-          color,
-          defaultPercent,
-        })),
-        presetBudgets: [50000, 100000, 250000, 500000],
-        defaultBudget: 100000,
-        currency: "USD",
-        currencySymbol: "$",
-      },
-      analytics: {
-        history: generateHistory(CATEGORIES),
-        benchmarks: BENCHMARKS,
-        stages: ["Seed", "Series A", "Series B", "Growth"],
-        defaultStage: "Series A",
-      },
-    };
-
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(response),
+/**
+ * Creates a new MCP server instance with tools and resources registered.
+ * Each HTTP session needs its own server instance because McpServer only supports one transport.
+ */
+function createServer(): McpServer {
+  const server = new McpServer({
+    name: "Budget Allocator Server",
+    version: "1.0.0",
+  });
+
+  server.registerTool(
+    "get-budget-data",
+    {
+      title: "Get Budget Data",
+      description:
+        "Returns budget configuration with 24 months of historical allocations and industry benchmarks by company stage",
+      inputSchema: {},
+      _meta: { [RESOURCE_URI_META_KEY]: resourceUri },
+    },
+    async (): Promise<CallToolResult> => {
+      const response: BudgetDataResponse = {
+        config: {
+          categories: CATEGORIES.map(({ id, name, color, defaultPercent }) => ({
+            id,
+            name,
+            color,
+            defaultPercent,
+          })),
+          presetBudgets: [50000, 100000, 250000, 500000],
+          defaultBudget: 100000,
+          currency: "USD",
+          currencySymbol: "$",
         },
-      ],
-    };
-  },
-);
-
-server.registerResource(
-  resourceUri,
-  resourceUri,
-  { description: "Interactive Budget Allocator UI" },
-  async (): Promise<ReadResourceResult> => {
-    const html = await fs.readFile(
-      path.join(DIST_DIR, "mcp-app.html"),
-      "utf-8",
-    );
-    return {
-      contents: [
-        { uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html },
-      ],
-    };
-  },
-);
+        analytics: {
+          history: generateHistory(CATEGORIES),
+          benchmarks: BENCHMARKS,
+          stages: ["Seed", "Series A", "Series B", "Growth"],
+          defaultStage: "Series A",
+        },
+      };
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(response),
+          },
+        ],
+      };
+    },
+  );
+
+  server.registerResource(
+    resourceUri,
+    resourceUri,
+    { description: "Interactive Budget Allocator UI" },
+    async (): Promise<ReadResourceResult> => {
+      const html = await fs.readFile(
+        path.join(DIST_DIR, "mcp-app.html"),
+        "utf-8",
+      );
+      return {
+        contents: [
+          { uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html },
+        ],
+      };
+    },
+  );
+
+  return server;
+}
 
 // ---------------------------------------------------------------------------
 // Server Startup
 // ---------------------------------------------------------------------------
 
 async function main() {
   if (process.argv.includes("--stdio")) {
-    await server.connect(new StdioServerTransport());
+    await createServer().connect(new StdioServerTransport());
   } else {
     const port = parseInt(process.env.PORT ?? "3103", 10);
-    await startServer(server, { port, name: "Budget Allocator Server" });
+    await startServer(createServer, { port, name: "Budget Allocator Server" });
   }
 }
 

examples/cohort-heatmap-server/server.ts

@@ -147,13 +147,13 @@ function generateCohortData(
   };
 }
 
-const server = new McpServer({
-  name: "Cohort Heatmap Server",
-  version: "1.0.0",
-});
+function createServer(): McpServer {
+  const server = new McpServer({
+    name: "Cohort Heatmap Server",
+    version: "1.0.0",
+  });
 
-// Register tool and resource
-{
+  // Register tool and resource
   const resourceUri = "ui://get-cohort-data/mcp-app.html";
 
   server.registerTool(
@@ -200,14 +200,16 @@ const server = new McpServer({
       };
     },
   );
+
+  return server;
 }
 
 async function main() {
   if (process.argv.includes("--stdio")) {
-    await server.connect(new StdioServerTransport());
+    await createServer().connect(new StdioServerTransport());
   } else {
     const port = parseInt(process.env.PORT ?? "3104", 10);
-    await startServer(server, { port, name: "Cohort Heatmap Server" });
+    await startServer(createServer, { port, name: "Cohort Heatmap Server" });
   }
 }