ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Use a Next.js MCP Server with Cursor

Connect Cursor to a running Next.js app with the official MCP bridge, then learn when a custom application MCP route is the better fit.

By the ScreenshotNeo team1 October 20266 min read

Use the official Next.js development MCP integration when you want Cursor to inspect a running Next.js project. Your project must use Next.js 16 or later. Add a root .mcp.json that starts next-devtools-mcp, run the Next.js development server, and enable the server in Cursor. The bridge connects Cursor to the development server’s built-in /_next/mcp endpoint.

This setup is for live development context: build and type errors, routes, runtime state, Server Actions, component information, and development logs. A custom MCP route such as /mcp is a separate architecture for exposing application-owned tools to external clients.

1. What you are connecting

The official bridge has three parts:

  1. Your Next.js 16+ development server.
  2. The next-devtools-mcp process, started with npx.
  3. Cursor, which launches the process and calls its MCP tools.

When the development server starts, Next.js exposes an internal /_next/mcp endpoint. The bridge discovers the running instance and forwards MCP requests to it. This is development-time introspection, not unrestricted production access. See the Next.js MCP documentation.

2. Prerequisites

  • A Next.js application running Next.js 16 or newer.
  • Node.js and the package manager already used by the project.
  • Cursor with MCP support enabled.
  • Permission to run npx and start the local development server.

Check the framework version before configuring anything:

npx next --version

If the project is older than Next.js 16, upgrade it first or use a separately implemented MCP server. The official development integration has a stated Next.js 16+ requirement.

3. Add the official Next.js MCP bridge

At the repository root, create a file named .mcp.json:

{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    }
  }
}

The -y flag allows npx to install or run the package without stopping for an interactive confirmation. Keep this file at the project root so the bridge can be associated with the correct application.

Start the development server with the command used by your project:

npm run dev

Equivalent commands are fine when the project uses another package manager:

pnpm dev
# or
yarn dev
# or
bun dev

If the server was already running when you added .mcp.json, stop and restart it so the integration can discover the current instance.

4. Register the server in Cursor

Cursor reads MCP configuration from either a project file at .cursor/mcp.json or the global file at ~/.cursor/mcp.json. If your team should share the configuration, create the project file and commit it.

The equivalent project configuration is:

{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    }
  }
}

Use one authoritative location for this server name. Defining next-devtools in both project and global files can make it unclear which definition Cursor is using. Cursor gives project configuration priority when the same server name appears in both locations. Configuration details are covered in Cursor’s MCP documentation.

5. Enable it and make the first request

  1. Keep npm run dev running.
  2. Open Cursor’s MCP or Customize controls.
  3. Confirm that next-devtools is enabled.
  4. Open a chat and ask for a task that needs live project context.

Useful first prompts include:

  • Inspect the current Next.js build errors.
  • List the routes in the running app.
  • Show the current runtime or type errors.
  • Explain which Server Actions are available.
  • Summarize recent development logs.

Cursor may ask for approval before invoking a tool. Review the request and approve it only when the operation matches your task.

6. Or skip the browser setup

If your goal is to capture pages for documentation, previews, regression checks, or an AI workflow, ScreenshotNeo provides a website screenshot API and MCP server. You can make one request instead of maintaining browser automation:

ScreenshotNeo API documentation

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. ScreenshotNeo also has an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

7. What the Next.js bridge exposes

The built-in development endpoint and bridge can provide current information about the running application, including:

Area Examples of useful requests
Build and type errors Find the current compilation or TypeScript failures.
Runtime state Inspect live development behavior and state.
Routes List routes and review route metadata.
Components and rendering Inspect component and rendering information.
Server Actions Review available actions and their context.
Logs Summarize development-server logs.

These tools are tied to a running development instance. Do not assume they provide production access, a database interface, or a shell.

8. Dev-tools bridge versus a custom application MCP server

Choose the architecture based on what the client needs:

Axis Next.js dev-tools MCP Custom application MCP route
Purpose Live development introspection for coding agents Expose application-owned tools to MCP clients
Configuration Root .mcp.json running next-devtools-mcp Application code, such as app/mcp/route.ts
Endpoint Built-in /_next/mcp An application route such as /mcp
Lifecycle Requires a running Next.js development server Deployed and operated with the application
Best fit Cursor-assisted debugging and project context Productized tools, custom authentication, and remote clients

The Vercel-maintained mcp-for-next.js template demonstrates the second design with mcp-handler, the MCP TypeScript SDK, and an App Router handler at app/mcp/route.ts. Its local endpoint is typically http://localhost:3000/mcp, and its deployment guidance requires Node.js 20 or later. Do not substitute /mcp for the dev-tools /_next/mcp endpoint.

9. Transport and authentication

Cursor documents three MCP transport choices:

  • stdio: Cursor launches a local process. This is the shortest path for next-devtools-mcp.
  • SSE: A server-sent-events connection for a local or remote service that supports it.
  • Streamable HTTP: An HTTP-based transport for supported local or remote deployments.

For local stdio servers, environment variables can hold secrets. For remote servers, use the authentication and environment interpolation supported by Cursor and the server. Cursor’s stdio-only envFile behavior does not apply to remote configurations, so do not commit access tokens in JSON.

10. Troubleshooting

Symptom Likely cause Fix
The server does not appear Wrong filename or location Check root .mcp.json and Cursor’s .cursor/mcp.json or ~/.cursor/mcp.json; restart Cursor.
No running app is found The development server is stopped Run npm run dev and restart the server after changing MCP configuration.
Version error or missing integration Next.js is older than 16 Upgrade the project or implement a separate custom MCP server.
Tool calls are blocked Cursor approval or enabled state Open Cursor’s MCP controls, enable the server, and review the approval prompt.
The wrong endpoint is being called /mcp and /_next/mcp were treated as the same design Use /_next/mcp for Next.js dev-tools and the route documented by your custom server for application tools.
Remote authentication fails Incorrect URL, headers, environment interpolation, or transport Verify each value and confirm that the server supports the selected Cursor transport.
npx waits for input The package install prompt was not suppressed Use the documented args value ["-y", "next-devtools-mcp@latest"].

11. Reliability, performance, and cost considerations

  • Reliability: The dev-tools bridge depends on the local development server. A stopped, crashed, or unreachable server means Cursor cannot inspect the app.
  • Freshness: Start or restart the development server after configuration changes so discovery uses the current instance.
  • Performance: Requests requiring route, component, runtime, or log inspection depend on the state of the running app. Keep the project in a usable development state and avoid treating a stale server as authoritative.
  • Security: Treat MCP tools as access to development context. Review Cursor approvals and keep credentials out of committed configuration.
  • Cost: The official local bridge is a development dependency path. A custom remote MCP deployment may add hosting and operational costs, which depend on your deployment.

12. FAQ

Can I use this with a production Next.js deployment?

The official integration is documented around a running development server. Use a separately designed and authenticated application MCP endpoint when you need a deployed service.

Should I use both .mcp.json and .cursor/mcp.json?

Pick one authoritative location for the server in your workflow. The first file is the Next.js bridge configuration shown by the official guide; the second is Cursor’s project-level configuration.

Does Cursor automatically approve every tool call?

Cursor may request approval before calling MCP tools. Check the server’s enabled state and respond to the approval prompt.

When is a custom route better?

Use a custom route when your application owns the tools, authentication, deployment lifecycle, or remote-client contract. Use the dev-tools bridge for local inspection while building.

Can ScreenshotNeo work with Cursor?

Yes. ScreenshotNeo provides an MCP server with screenshot, page-info, and PDF tools for Cursor and other MCP clients. Its API is also available as a direct HTTP request.

Keep reading