next-devtools-mcp: Giving AI Agents Real-Time Access to Your Next.js App

Every AI-native development workflow eventually hits the same wall: the coding agent knows your filesystem but not your running app. It can read the code that defines a Server Action but cannot tell you whether that action is throwing at runtime. It can grep for route segments but not query the actual route table your dev server resolved from the filesystem.

Next.js 16 closes this gap with a built-in MCP endpoint. Pair it with the next-devtools-mcp package and any MCP-compatible coding agent — Claude Code, Cursor, or any agent using the Model Context Protocol — gains real-time access to your running application.

The setup

Add a .mcp.json file at the root of your project:

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

That is the entire configuration. When you start the dev server, next-devtools-mcp discovers and connects to the /_next/mcp endpoint Next.js 16 exposes automatically. Restart your agent session and it gains access to a new set of tools.

What agents can see

The tools available through next-devtools-mcp fall into two groups.

Application state:

• get_errors — current build errors, runtime errors, and type errors, as they appear in the browser session
• get_logs — path to the dev log file with browser console output and server logs
• get_page_metadata — routes, components, and rendering details for a given page
• get_project_metadata — project structure, configuration, and the dev server URL
• get_routes — the full route table resolved from the filesystem, grouped by App Router / Pages Router, with dynamic segments shown as [param] patterns
• get_server_action_by_id— look up a Server Action's source file and function name from its runtime ID

There is also a Next.js documentation query tool that lets agents ask questions and get documentation-backed answers, and migration helpers that run codemods against your project.

Why this matters for AI-native teams

The most common class of agent error in Next.js projects is stale-context hallucination: the agent writes code that was correct three versions ago, or that would work except for the runtime error the agent cannot see.

Real-time access to the running app changes this. If a Server Action is failing, the agent can call get_errors and read the exact stack trace before proposing a fix. If it needs to add a new dynamic route, it can call get_routes to see what already exists, then get_page_metadata to understand the rendering mode — before writing a single line.

The feedback loop shrinks from the usual cycle of write code → reload → read error → write fix → repeat, to: describe the problem → agent reads live errors → agent writes a targeted fix.

How it works under the hood

Next.js 16 exposes /_next/mcp only in development mode. The endpoint runs inside the existing dev server process — no extra port, no additional daemon. next-devtools-mcp acts as an adapter that translates MCP tool calls into HTTP requests to that endpoint and forwards the responses back to whatever agent is driving it.

One package can connect to multiple Next.js instances on different ports simultaneously, which matters if you run a monorepo with several apps side by side.

One thing to watch

The /_next/mcp endpoint is development-only — it is not present in production builds and next build will not embed it. That is intentional: it exposes internal runtime state you do not want public. Do not attempt to proxy it or enable it in a production environment.

The short version

Add .mcp.json with the next-devtools-mcp config, start your dev server, and your coding agent gains get_errors, get_routes, and four other tools that read your running application in real time. The agent stops guessing at runtime state and starts reading it.