fix: enhance MCP server error handling and improve CORS headers for better client compatibility

Author: regenrek

packages/mcp/src/index.ts

@@ -355,7 +355,11 @@ export async function handleMcpHttpRequest(
   // CORS + expose session id per SDK guidance
   try {
     res.setHeader('Access-Control-Allow-Origin', '*');
-    res.setHeader('Access-Control-Allow-Headers', 'content-type, mcp-session-id');
+    // Allow both canonical and lowercase variants; include Accept & MCP-Protocol-Version for spec-compliant clients
+    res.setHeader(
+      'Access-Control-Allow-Headers',
+      'content-type, accept, mcp-session-id, Mcp-Session-Id, mcp-protocol-version, MCP-Protocol-Version'
+    );
     res.setHeader('Access-Control-Allow-Methods', 'POST, GET, DELETE, OPTIONS');
     res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id');
   } catch {}
@@ -428,9 +432,13 @@ export async function handleMcpHttpRequest(
           res.setHeader('content-type', 'application/json');
         } catch {}
       }
+      // Make the guidance explicit: POST initialize → read Mcp-Session-Id → include for GET/DELETE (+ protocol header)
       res.end(JSON.stringify({
         jsonrpc: '2.0',
-        error: { code: -32000, message: 'Method not allowed. Initialize with POST to obtain Mcp-Session-Id, then include it for GET/DELETE.' },
+        error: {
+          code: -32000,
+          message: 'Method not allowed. To open a server stream, first POST an InitializeRequest to this MCP endpoint and read the Mcp-Session-Id response header. Include that Mcp-Session-Id (and MCP-Protocol-Version) on all subsequent GET/DELETE/POST requests.'
+        },
         id: null
       }));
       return;

packages/next/src/mcp-route.ts

@@ -28,7 +28,15 @@ function copyHeaders(src: Headers): Headers {
 }
 
 async function proxy(method: string, req: NextRequest): Promise<Response> {
-  await ensureLocalHttpServer();
+  try {
+    await ensureLocalHttpServer();
+  } catch (err: any) {
+    const message = `[browser-echo] MCP server failed to start: ${err?.message || String(err)}`;
+    return new Response(JSON.stringify({ error: message }), {
+      status: 500,
+      headers: { 'content-type': 'application/json' }
+    });
+  }
 
   // Build upstream URL and preserve query string
   const upstreamBase = new URL(getLocalMcpUrl());

packages/next/src/route.ts

@@ -10,7 +10,7 @@ export const runtime = 'nodejs';
 export const dynamic = 'force-dynamic';
 
 export async function GET(req: NextRequest) {
-  try { startMcpServer(); } catch {}
+  try { startMcpServer(); } catch (e) { console.error('[browser-echo] MCP server failed to start:', e); }
   const session = req.nextUrl.searchParams.get('session') || undefined;
   const text = getLogsAsText(session || undefined);
   return new NextResponse(text, {
@@ -23,7 +23,7 @@ export async function GET(req: NextRequest) {
 }
 
 export async function POST(req: NextRequest) {
-  try { startMcpServer(); } catch {}
+  try { startMcpServer(); } catch (e) { console.error('[browser-echo] MCP server failed to start:', e); }
   const mcpOn = _mcpEnvEnabled();
 
   let payload: Payload | null = null;

packages/nuxt/src/runtime/server/handler.ts

@@ -6,7 +6,7 @@ type Entry = { level: Level | string; text: string; time?: number; stack?: strin
 type Payload = { sessionId?: string; entries: Entry[] };
 
 export default defineEventHandler(async (event) => {
-  try { startMcpServer(); } catch {}
+  try { startMcpServer(); } catch (e) { console.error('[browser-echo] MCP server failed to start:', e); }
   const mcpOn = _mcpEnvEnabled();
 
   const method = String(event.node?.req?.method || 'POST').toUpperCase();

packages/nuxt/src/runtime/server/mcp.ts

@@ -3,7 +3,7 @@ import { handleMcpHttpRequest, startMcpServer } from '@browser-echo/mcp';
 
 export default defineEventHandler(async (event) => {
   // Ensure MCP server is ready
-  try { startMcpServer(); } catch {}
+  try { startMcpServer(); } catch (e) { console.error('[browser-echo] MCP server failed to start:', e); }
 
   const req = event.node.req;
   const res = event.node.res;

packages/vite/src/index.ts

@@ -74,7 +74,16 @@ export default function browserEcho(opts: BrowserLogsToTerminalOptions = {}): im
     },
     configureServer(server) {
       if (!options.enabled) return;
-      try { startMcpServer(); } catch {}
+      try {
+        startMcpServer();
+        try {
+          server.config.logger.info(`${options.tag} MCP endpoint mounted at ${options.mcpRoute}`);
+        } catch {}
+      } catch (e: any) {
+        try {
+          server.config.logger.error(`${options.tag} MCP server failed to start: ${e?.message || e}`);
+        } catch {}
+      }
       server.middlewares.use(options.mcpRoute, (req: IncomingMessage, res: ServerResponse, _next: () => void) => {
         const m = (req.method || 'GET').toUpperCase();
         (async () => {