#139
Issues/vercel-labs/mcp-handler/#139

MCP server in NextJS app crashes API Endpoints with error - No response is returned from route handler

Openakshay-kumardhage-deelopened 10mo ago

Problem

When a MCP server is built with latest versions mcp-handler@1.0.6 and @modelcontextprotocol/sdk@1.25.2 the Nextjs App router API endpoints throw below error

Error: Error: No response is returned from route handler '[project]/app/api/health/route.ts'. Ensure you return a `Response` or a `NextResponse` in all branches of your handler. at ignore-listed frames

app/api/health/route.ts

import { NextResponse } from "next/server"
export const GET = () => {
    return NextResponse.json({
        status: "Ok"
    })
}

Same error persists for versions 1.25.X of @modelcontextprotocol/sdk along side of mcp-handler@1.0.6

The only properly working version found - mcp-handler@1.0.6 and @modelcontextprotocol/sdk@1.24.3

Expected

NextJS API endpoints must keep functioning correctly along side of MCP routes in same app, when using mcp-handler@1.0.6 and @modelcontextprotocol/sdk@1.25.x

Reproducible Steps

  1. Create a NextJS App Router project e.g. npx create-next-app@latest my-app --yes
  2. Install dependencies with latest versions - mcp-handler@1.0.6 and @modelcontextprotocol/sdk@1.25.2
  3. Create a simple GET API endpoint e.g. app/api/health/route.ts as above
  4. Create a simple MCP server e.g. follow mcp-handler example - https://www.npmjs.com/package/mcp-handler
  5. Run the app and connect to the MCP Server from tools like Cursor or MCP Inspector (MUST connect to MCP first)
  6. Ping the api/health endpoint. Observe that server starts to throw error - Error: No response is returned from route handler '[project]/app/api/health/route.ts'. Ensure you return a `Response` or a `NextResponse` in all branches of your handler

Activity

10
balataca10mo ago

For those who need a workaround to use version @modelcontextprotocol/sdk@1.25.2 that doesn't have a security vulnerability:

  1. Remove mcp-handler:
npm uninstall mcp-handler
  1. Install @modelcontextprotocol/sdk@1.25.2
npm install @modelcontextprotocol/sdk
  1. Create the mcp server and export the handlers you need:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
import type { NextRequest } from "next/server";

const handler = async (req: NextRequest) => {
  // Create MCP server
  const server = new McpServer(
    {
      name: "mcp-server",
      version: "1.0.0",
    },
    {
      capabilities: {
        tools: {},
      },
    },
  );

  // Register tools, prompts, resources etc.
  // server.registerTool() [...]

  const transport = new WebStandardStreamableHTTPServerTransport();
  await server.connect(transport);

  return transport.handleRequest(req);
};

// You can also use DELETE and other methods with the handler
export { handler as GET, handler as POST };

It is working great for me after I removed the mcp-handler dependency. I moved the server creation logic to a factory createMcpServer, but you can also register directly on the handler.

HemangRajvanshy10mo ago

The issue is tracked here: https://github.com/modelcontextprotocol/typescript-sdk/issues/1369

TiKa-Nexus9mo ago

I stumbled upon a problem in my app which likely results from the same underlying issue.

Whenever I run my app on localhost and trigger the mcp server, also hosted on the same localhost port, the app breaks. Its whatever is first "using" the server works but the other one does not. So, I can either use only mcp or only use the app on localhost not both.

The error is always the same, once I try to use the other:

 TypeError: Expected an instance of Response to be returned
    at ignore-listed frames

I use mcp-handler@1.0.7and @modelcontextprotocol/sdk@1.25.2

TiKa-Nexus9mo ago

They introduced a fix. Updating to @modelcontextprotocol/sdk@1.25.3 resolves the issue. See https://github.com/modelcontextprotocol/typescript-sdk/issues/1369

xqe20119mo ago

Duplicate with #140

andershagbard9mo ago

They introduced a fix. Updating to @modelcontextprotocol/sdk@1.25.3 resolves the issue. See modelcontextprotocol/typescript-sdk#1369

Seems like something broke again in 1.26.0. Downgrading to 1.25.3 worked for me.

dandrei9mo ago

Thanks @balataca, your example worked perfectly. I couldn't get the mcp-handler example to run at all, which really defeats the purpose of having this project in the first place.

doinghun8mo ago

Confirming this is reproducible in a real Next.js app (not just a minimal repro).

Environment:

  • next 16.0.10 (App Router + Turbopack)
  • mcp-handler 1.0.7
  • @modelcontextprotocol/sdk 1.25.2 (fails), 1.25.3 (works)
  • pnpm workspace, local macOS (non-Docker)

Observed behavior:

  • Normal app/API routes work on startup.
  • After the first successful MCP request (POST /api/v1/ai/mcp), unrelated App Router API routes begin failing with:
    • No response is returned from route handler ...
    • TypeError: Expected an instance of Response to be returned
  • In our case this hit routes like:
    • /api/workspaces/[workspaceId]/credits
    • /api/workspaces/[workspaceId]/waterfall-runs
    • /api/workspaces/[workspaceId]/waterfall-configs

Workaround/fix on our side:

  • Pinning @modelcontextprotocol/sdk to 1.25.3 resolved the issue consistently.
fIa5h7mo ago
  • Downgrading/pinning to 1.25.3 worked for me. This is a nasty little bug.
umitkaanusta7mo ago
  • Downgrading/pinning to 1.25.3 worked for me. This is a nasty little bug.

+1, I'm using mcp-handler 1.0.7 and this was the lowest-effort solution for me