How do Next.js Devtools MCP and AGENTS.md change AI-assisted debugging?

Q: How do Next.js Devtools MCP and AGENTS.md change AI-assisted debugging?

**Target Audience:** Frontend engineers preparing for Next.js interviews — no prior knowledge of MCP needed. **Difficulty:** Medium > **How to read this doc:** Each idea is explained in plain language first, then tagged with `📌 Interview term:`. Every behaviour claim was checked against the Next.js 16.4.2 docs (the AI agents and MCP guides, `agentRules`, `agentFeedback`) and, in the **Verified** section, against a 16.4.2 `next dev` server: its terminal, the files it wrote, and JSON-RPC calls to `/_next/mcp`. ## 1. Why This Even Matters — A Story First Imagine hiring a very fast contractor who learned plumbing from a manual printed three years ago, and who cannot see inside your walls. They work quickly, but they install last generation's fittings and guess where the leak is. Coding agents on a Next.js project have exactly those two problems. Their training data describes older Next.js versions (middleware instead of proxy, synchronous `params`, old caching defaults), and they cann

The problem

Question presented to candidate: "Half our team now uses coding agents like Claude Code or Cursor on our Next.js app. The agents keep writing Next.js 14 code and guessing at errors. What do the Next.js Devtools MCP server and the generated AGENTS.md do about that, and what would you set up?"

What a strong answer should cover:

Version-matched docs: since 16.2 the docs for the installed version ship in node_modules/next/dist/docs/; since 16.3 next dev writes a managed block in AGENTS.md (when it detects a coding agent) telling agents to read them instead of relying on training data.
The MCP endpoint: next dev (16+) serves Model Context Protocol at /_next/mcp with tools such as get_errors, get_logs, get_routes, get_server_action_by_id, get_compilation_issues and compile_route; the next-devtools-mcp package connects agent clients to it.
This gives agents the running app's view (browser errors, hydration errors, compile issues, routes) as structured data instead of screenshots or guesses.
Control: agentRules: false removes the managed block, experimental.mcpServer: false disables the endpoint; 16.4 added experimental.agentFeedback (opt-in issue reports) and next upgrade --agent.
Limits: dev only, the agent still needs to verify in a browser, and the managed block is regenerated if deleted, so commit it.

Clarifying questions expected:

"Which agents and editors do people use?" — the MCP client setup differs; AGENTS.md is read by most.
"Are there internal rules we want agents to follow?" — they go in the same file outside the managed markers.

Code / implementation expected: Optional — .mcp.json, the config options, and an example tool call.

nextjs
ai
debugging
mcp
next-16

Try it yourself

Sketch your approach before you read the solution. That is what the interview tests.

Stuck? Get a hint.

A short nudge toward the approach. It will not give the answer away.

Solution

Target Audience: Frontend engineers preparing for Next.js interviews — no prior knowledge of MCP needed. Difficulty: Medium

How to read this doc: Each idea is explained in plain language first, then tagged with 📌 Interview term:. Every behaviour claim was checked against the Next.js 16.4.2 docs (the AI agents and MCP guides, agentRules, agentFeedback) and, in the Verified section, against a 16.4.2 next dev server: its terminal, the files it wrote, and JSON-RPC calls to /_next/mcp.

1. Why This Even Matters — A Story First

Imagine hiring a very fast contractor who learned plumbing from a manual printed three years ago, and who cannot see inside your walls. They work quickly, but they install last generation's fittings and guess where the leak is.

Coding agents on a Next.js project have exactly those two problems. Their training data describes older Next.

The solution is hidden so you can try first

9 min read · 8 sections

Read the code

Register next-devtools-mcp for agent clients

# Option 1: let add-mcp write the config for the agents installed on this machine
npx add-mcp next-devtools-mcp@latest

# Option 2: commit a project-level .mcp.json
cat > .mcp.json <<'JSON'
{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    }
  }
}
JSON

next.config.ts: agent-related options

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  agentRules: true, // 16.3+: keep the managed AGENTS.md block (false removes it on next dev in 16.4)
  experimental: {
    mcpServer: true, // the /_next/mcp endpoint in next dev (default true)
    agentFeedback: false, // 16.4, opt-in issue-report drafts for review
  },
};

export default nextConfig;

Calling the MCP endpoint directly (the lab script)

async function mcp(method: string, params: Record<string, unknown> = {}) {
  const res = await fetch("http://localhost:3000/_next/mcp", {
    method: "POST",
    headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
  });
  const text = await res.text();
  const line = text.split("\n").find((l) => l.startsWith("data:"));
  return JSON.parse(line ? line.slice(5) : text);
}

const tools = await mcp("tools/list");
const errors = await mcp("tools/call", { name: "get_errors", arguments: {} });
console.log(tools.result.tools.map((t: { name: string }) => t.name), errors.result.content[0].text);

export {}; // a module, so top-level await is allowed

Discussion

Other approaches, follow-ups and how it went in real interviews.

Sign in to join the discussion.

No comments yet. Share how you would answer it.

The solution is hidden so you can try first

Keep your momentum going.