Next.js MCP Server: Set Up next-devtools-mcp for Your Agent

You ask your coding agent to fix a hydration error. It reads the component, guesses, edits, and tells you it's fixed. You refresh the page. Same error.

The agent never saw the error. It saw your code.

The Next.js MCP server closes that gap. Since Next.js 16, the dev server exposes a built-in MCP endpoint at /_next/mcp, and a small package called next-devtools-mcp connects your agent to it. Now the agent can ask the running app what's broken, which routes exist, and what the logs say, instead of inferring all of it from source files.

Here's the short version, as of October 2026:

The rest of this guide covers what the endpoint exposes, how to set it up in Claude Code and with a plain .mcp.json, and what to check when it won't connect.

What the Next.js MCP server actually is

If MCP is new to you, the one-line version: the Model Context Protocol is an open standard that lets AI agents call tools in other applications through one shared interface. Our what is MCP explainer goes deeper.

The Next.js MCP guide describes two parts that work together.

The endpoint. In Next.js 16 and later, next dev serves an MCP endpoint at /_next/mcp. It reports the running app's view of errors, routes, logs, and compilation issues. It's enabled by default, and you don't configure anything to turn it on.

The connector. Your agent doesn't talk to that endpoint directly. You install next-devtools-mcp, which Vercel's README calls a "thin connector." It scans common ports for running Next.js 16+ dev servers, lists each one's tools, and forwards calls to the right one.

That split matters for one practical reason: you can run several Next.js apps on different ports and the agent gets a single set of tools for all of them. It picks the server by port.

The tools your agent gets

The connector itself exposes four tools. Two do real work, and two are what the README calls gateways.

The gateways don't fetch docs or drive a browser themselves. They tell the agent where the docs live, or how to install and run the CLI, and the agent does the rest directly. The README says that's faster than proxying through MCP.

The runtime tools behind nextjs_call

This is where the value is. Through nextjs_call, the agent can reach the tools the dev server exposes at /_next/mcp:

The README notes the runtime tool list varies by Next.js version, so nextjs_index is the source of truth for what your install exposes.

The two Turbopack tools are the underrated ones. The Next.js docs point out that an agent can check whether its edits compile straight from the running dev server, instead of running next build while it's still editing. That's a much tighter loop than a full build after every change.

Requirements before you start

From the next-devtools-mcp README:

• Node.js v20.19 or a newer LTS version
• npm or pnpm, so the agent can launch the package with npx
• Next.js 16 or later with a running dev server. This is only required for nextjs_index and nextjs_call. The two gateway tools work without one.

If you're on Next.js 15 or earlier, the /_next/mcp endpoint simply doesn't exist. The connector will install fine and then find nothing to talk to.

Set up the Next.js MCP server in Claude Code

Claude Code adds local servers with claude mcp add. The Claude Code MCP docs put Claude's own options first, then a -- (double dash), then the command that launches the server. Everything after -- goes to the server untouched.

For the Next.js MCP server, that's:

claude mcp add --transport stdio next-devtools -- npx -y next-devtools-mcp@latest

That writes to local scope by default: it loads only in the current project and stays private to you. Two other scopes are worth knowing:

Project scope is the one to use for a team Next.js repo. Add --scope project and Claude Code creates or updates .mcp.json for you, which you commit so everyone gets the same tools:

claude mcp add --transport stdio next-devtools --scope project -- npx -y next-devtools-mcp@latest

Then check it:

claude mcp list
claude mcp get next-devtools

One thing that surprises people: Claude Code asks for approval before it uses a project-scoped server from .mcp.json in an interactive session. Until you run claude in the folder and approve it, the server shows as pending. That's a security feature, not a bug. A cloned repo can't approve its own servers.

For the full set of flags, environment variables, and scope rules, our Claude Code MCP server configuration guide walks through each one.

The generic .mcp.json config

If you'd rather write the file by hand, or you use a different MCP client, this is the config both the Next.js docs and the README give:

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

Save it as .mcp.json at your project root. The @latest tag keeps your client on the newest release each time the agent launches it.

The README also lists one-line setup commands for Codex, Cursor, Gemini, Google Antigravity, VS Code, Amp, and Warp. And if you have several agents installed, it suggests npx add-mcp next-devtools-mcp@latest to add the server to all of them at once.

Using it: the dev loop

The workflow from the Next.js docs is four steps:

1. Start your dev server with npm run dev, pnpm dev, yarn dev, or bun dev.
2. Let the agent connect. next-devtools-mcp discovers the running instance on its own. No port config needed.
3. Open the pages you're working on in a browser. get_errors and get_page_metadata read from active browser sessions. A page nobody has opened has no errors to report.
4. Ask about the running app.

Prompts that work well:

• "What errors are in my Next.js app right now?"
• "Show me the structure of my routes."
• "What's in the dev server logs?"
• "Check whether /blog/[slug] compiles."

Behind the scenes, the agent calls nextjs_index to find the server, then nextjs_call with something like toolName: "get_errors" on port 3000. In the docs' own example, the agent finds a hydration mismatch on /about, explains which text differs between server and client, fixes the component, and checks again.

That last step is the point. The agent can verify its fix against the running app, not just declare it done.

How it fits with Next.js's other agent tooling

The MCP server is one piece of a bigger push. The Next.js AI coding agents guide lays out the rest:

• Bundled docs. Next.js 16.2 and later ship version-matched documentation in node_modules/next/dist/docs/, so an agent can read the APIs your installed version actually supports.
• Managed AGENTS.md. In Next.js 16.3 and later, next dev writes a block into AGENTS.md that tells agents to read those bundled docs before writing code.
• Skills. Workflows like next-dev-loop are distributed as agent skills. The docs note that next-dev-loop calls /_next/mcp directly, so it works even without next-devtools-mcp installed.
• Browser view. The agent-browser CLI exposes the DOM, console, network, and Web Vitals as structured text. The docs describe the MCP server as the framework's view and agent-browser as the browser's view.

This also explains a change older tutorials miss. next-devtools-mcp 0.4.0 removed tools that earlier write-ups describe, including init, upgrade_nextjs_16, and enable_cache_components. Docs and migration workflows moved out of the server. If a guide tells you to call upgrade_nextjs_16, it was written for 0.3.x.

You'll also find community-built Next.js MCP servers on GitHub and in MCP directories. Check what they actually connect to before installing one. The official pair, the built-in endpoint plus next-devtools-mcp, is what the Next.js docs document. Our roundup of the best MCP servers covers how to vet the rest.

Troubleshooting a Next.js MCP connection

"No server info found." The README's checklist: start the dev server, confirm you're on Next.js 16 or later, and make sure it started without errors. The endpoint only exists on 16+.

The server never connects. The Next.js docs add three more checks:

• experimental.mcpServer isn't set to false in next.config. That flag is how you turn the endpoint off.
• The server is actually in your agent's config, for example in .mcp.json.
• Your agent has reloaded its MCP config. Restart the dev server too if it was already running.

ERR_MODULE_NOT_FOUND mentioning next-devtools-mcp/dist. Clear your npx cache and restart the MCP client. The package reinstalls fresh.

Errors come back empty. Open the page in a browser. The docs say get_errors reads from active browser sessions.

On telemetry: the README says next-devtools-mcp collects anonymous usage data (tool names, error events, session metadata) but not your code, file paths, or tool arguments. Set NEXT_TELEMETRY_DISABLED=1 to opt out.

Where Taku fits

The Next.js MCP server is a great fit if you already run a Next.js project and an agent in your terminal every day. Plenty of people never get that far. They see a working agent setup shared online and stall on the install, the config file, and the scopes.

If the setup step is where you keep stalling, Taku mirrors a working AI setup into a desktop workspace and runs it, so you can use a power user's configuration without reproducing their environment first. Taku is in Beta, and the Mac app is available now.

FAQ

What is the Next.js MCP server?

It's the MCP endpoint built into the Next.js 16+ dev server at /_next/mcp. It gives coding agents the running app's errors, routes, logs, and compilation issues. You connect an agent to it through the next-devtools-mcp package.

Do I need next-devtools-mcp if Next.js already has an MCP endpoint?

For most agents, yes. next-devtools-mcp is the connector the Next.js docs tell you to install. It discovers running dev servers, including several on different ports, and forwards your agent's calls. Skills such as next-dev-loop call /_next/mcp directly and don't need it.

How do I add the Next.js MCP server to Claude Code?

Run claude mcp add --transport stdio next-devtools -- npx -y next-devtools-mcp@latest. Add --scope project to write it to a shared .mcp.json your team can commit.

Which Next.js version supports nextjs mcp?

Next.js 16 and later. The /_next/mcp endpoint doesn't exist in earlier versions, so nextjs_index and nextjs_call will find nothing. The bundled docs that nextjs_docs points to arrived in 16.2.

How do I turn off the Next.js MCP endpoint?

Set experimental.mcpServer to false in next.config. The endpoint is on by default in development.

Why can't I find upgrade_nextjs_16 in next-devtools-mcp?

Version 0.4.0 removed it, along with init and enable_cache_components. Upgrade and Cache Components workflows are now distributed as agent skills, and docs come from the copy bundled in node_modules/next/dist/docs/.