Next.js Enabling Next.js MCP Server for coding agents

Every AI coding assistant working on a Next.js project faces the same handicap: it can read your source files, but it has no idea what's actually happening in the running application. It can't see the hydration error currently showing in your browser. It can't tell you which Server Action a click handler resolves to. It's reasoning about your code from static text, the same way it would reason about a code snippet pasted into a chat window, when the far more useful signal — what's actually breaking, right now, in the dev server you have open in another tab — is sitting a few feet away and completely invisible to it.

Next.js 16 closes that gap with a built-in Model Context Protocol (MCP) endpoint, paired with an official package called next-devtools-mcp that any MCP-compatible coding agent can connect to. Once it's wired up, your agent stops guessing about your app's state and starts querying it directly. This article covers what that actually buys you, how to set it up, and where the rough edges are.

What MCP is, briefly

The Model Context Protocol is an open standard — not a Next.js invention — for letting AI agents talk to external tools and data sources through a consistent interface. Anthropic originally proposed it, and it's since been adopted broadly enough that "MCP server" now means something specific across the AI tooling ecosystem: a small process (or, in this case, an endpoint) that exposes a defined set of callable tools, which any compliant client can discover and invoke without custom integration code per tool.

Next.js's contribution here isn't inventing a new protocol — it's exposing your dev server's internals through that already-standardized interface, so any MCP-aware agent (Claude Code, Cursor, and others) gets access without Next.js needing to build a bespoke integration for each one.

What it requires

This feature needs Next.js 16 or above — nothing about it works on 15 or earlier, since the underlying MCP endpoint (/_next/mcp) is new server plumbing introduced in this release. If you're on an older version, this is one more reason on the pile to work through the upgrade guides before reaching for it.

Setting it up

The setup is refreshingly small. Add a .mcp.json file to your project root:

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

That's the entire configuration. Start your dev server as usual:

npm run dev

next-devtools-mcp automatically discovers the running Next.js instance and connects to it — there's no port to configure manually, no separate process to babysit alongside your dev server. If your coding agent has already loaded the MCP configuration from .mcp.json, it picks up the connection the next time you ask it something.

One detail worth flagging for teams: .mcp.json is a project file, which means it's naturally something you'd commit so every contributor's agent gets the same tooling without individually configuring it. There's nothing secret in it — it's just an npx invocation — so there's no reason to gitignore it the way you might a .env file.

What the agent can actually see

The tool surface splits into two rough categories, and it's worth knowing both because they solve different problems.

Application runtime access covers the "what is currently happening" questions: build errors, runtime errors, and type errors currently present in your dev server; live application state; page-level metadata (which routes exist, which components render them); Server Action inspection; and access to development server logs, including forwarded browser console output.

Development tooling is a smaller but genuinely useful pair: a documentation gateway that points the agent at the exact version-matched docs bundled in your own node_modules/next/dist/docs/ (rather than whatever the model's training data happened to contain about some other Next.js version), and Playwright MCP integration for verifying rendered pages in an actual browser.

Concretely, the tools an agent can call include get_errors, get_logs, get_page_metadata, get_project_metadata, get_routes, get_server_action_by_id, get_compilation_issues, and compile_route. A couple of these are worth calling out specifically:

• get_routes scans your filesystem and returns every route as an entry point, grouped by router type (App Router vs. Pages Router if you have both), with dynamic segments shown as [param] or [...slug] patterns — genuinely useful for an agent trying to figure out where a new feature should live without you having to explain your routing conventions in the prompt.
• compile_route triggers on-demand compilation of a specific route without making an actual HTTP request to it. You can pass either a route specifier like /blog/[slug] (as returned by get_routes) or a concrete path like /blog/hello-world, and it resolves that against the dev router's live route table. This is a genuinely different capability from just curling the route yourself — it surfaces compilation issues directly, without needing a browser or client in the loop, and it only works with Turbopack.
• get_compilation_issues is the project-wide sibling — bundler warnings and errors across the whole app, also Turbopack-only.

That Turbopack restriction is worth sitting with for a second. If your project still runs on webpack, those two tools simply won't function. Given that Turbopack has become the default dev bundler in recent Next.js releases, this mostly matters if you're on an older config or have deliberately opted back into webpack for compatibility reasons — but if you find compile_route silently doing nothing useful, that's the first thing to check.

What this changes about the actual workflow

The genuinely useful shift here isn't "the agent can now write code" — it already could. It's that the feedback loop between "agent makes a change" and "agent knows whether that change worked" collapses from "ask the human to check" to "query the running app directly." A concrete illustration, straight from the kind of interaction this enables:

User: "What errors are currently in my application?"

The agent doesn't ask you to paste console output. It calls get_errors against your live dev server, gets back structured data — for example, a hydration mismatch on /about where the server rendered "server" and the client rendered "client" — and can go straight to proposing a fix, because it has the actual error, not your paraphrase of it. In a real session this looked like:

⏺ next-devtools - nextjs_runtime (MCP)(action: "discover_servers")
⏺ next-devtools - nextjs_runtime (MCP)(action: "call_tool", toolName: "get_errors")

⏺ I found a hydration error on the /about page. The error shows that the server is
  rendering "server" but the client is rendering "client", causing a mismatch.

The same pattern extends past error-fixing. Asked to help upgrade to Next.js 16, an MCP-connected agent can run the official upgrade codemod itself (npx @next/codemod@latest upgrade latest) and then walk through breaking changes with you, rather than reciting a generic migration checklist from memory. Asked a conceptual question — "when should I use use client?" — it reads the version-accurate docs bundled with your actual installed Next.js version, not whatever it remembers from training, and answers against that.

That last point deserves emphasis because it's easy to undersell: Next.js's App Router has changed meaningfully across versions, and this very project runs 16.3.0, where conventions like Proxy replacing Middleware have already shifted once. A model's training data has a cutoff; your node_modules doesn't. Wiring the agent to read from the latter instead of relying on the former is, in a very literal sense, the difference between a stale answer and a correct one — worth noting given this article and its siblings in this series are themselves being written by exactly this kind of agent, sourced from exactly this kind of live documentation fetch rather than memory.

How it actually works under the hood

Next.js 16+ ships a built-in MCP endpoint at /_next/mcp, running inside your dev server process. next-devtools-mcp is a separate, thin package that discovers and talks to that endpoint — and it's explicitly designed to handle multiple Next.js instances running on different ports simultaneously, forwarding tool calls to whichever one is relevant.

That architectural split matters more than it looks: the agent-facing interface (next-devtools-mcp) is decoupled from the actual implementation living inside each Next.js dev server. That's what lets the same MCP client work identically across different Next.js projects without per-project glue code, and it's also presumably how the Next.js team plans to keep expanding the tool surface without breaking existing agent integrations — new tools get added to the endpoint side, and clients simply see more capabilities appear.

Troubleshooting

If your agent isn't connecting, the checklist is short and mostly mechanical:

• Confirm you're actually on Next.js 16 or later — this is the single most common reason it silently doesn't work, since older versions have no /_next/mcp endpoint to connect to at all.
• Confirm next-devtools-mcp is actually present in .mcp.json — a typo in the server name or a missing -y flag on the npx invocation is easy to miss.
• Make sure the dev server (npm run dev) is actually running — there's nothing for the MCP client to discover if the app isn't started.
• If the dev server was already running before you added or edited .mcp.json, restart it — configuration changes here aren't hot-reloaded into an already-running instance.
• Confirm your specific coding agent has actually loaded the MCP server config. Different agents load .mcp.json at different points (some at session start, some requiring an explicit reconnect), so "it's configured but not working" is often just "it hasn't been picked up yet by this particular client."

A few things worth knowing that aren't in the setup docs

This is explicitly a moving target. The docs are upfront that the Next.js team is actively adding tools — the list above is what exists as of this writing, not a fixed API surface. If you're building tooling or workflows around specific tool names, expect the roster to grow rather than assume it's final.

It's a development-time feature, not a production one. Everything here is scoped to your dev server. There's no equivalent surface for introspecting a production deployment through MCP, and that's a deliberate boundary — you don't want a protocol exposing internal application state to be reachable from a live, internet-facing instance.

The Playwright MCP integration is optional but worth pairing. On its own, next-devtools-mcp gives an agent visibility into build/runtime state, but no way to actually see a rendered page. Pairing it with Playwright MCP closes that loop — the agent can make a change, confirm via get_errors that nothing broke at the code level, and then actually look at the resulting page in a browser to confirm it looks right, all without you tabbing over to check yourself.

Treat .mcp.json like any other tooling config, but be aware of what it grants. It doesn't expose secrets by itself, but it does grant any connected agent read access to your application's internal error state, route structure, and Server Action mappings while your dev server is running. That's a reasonable trust boundary for a solo developer or a trusted team; it's worth thinking about deliberately if you're running an agent you don't fully trust against a codebase with sensitive routing or logic you'd rather it not enumerate wholesale.

Key Takeaways

Question	Answer
Minimum Next.js version	16
What you install	next-devtools-mcp (via .mcp.json, no separate global install)
Where the endpoint lives	/_next/mcp, inside your dev server
Turbopack-only tools	get_compilation_issues, compile_route
Works in production?	No — development-time only
Biggest practical win	Agents query real errors/state instead of relying on your paraphrase or stale training data
Common failure cause	Dev server not restarted after adding/editing .mcp.json

The value here isn't flashy, but it's real: every minute an agent spends asking you to describe what's broken, instead of just checking, is a minute wasted on both ends. Wiring up next-devtools-mcp turns "can you paste the error" into "let me check" — and for a five-minute setup, that's a good trade.