Next.js 16 Devtools MCP for Claude Code and GitHub Copilot

Your AI agent does not need you to copy-paste stack traces anymore. Next.js 16 ships MCP tooling that lets Claude Code or GitHub Copilot ask your running dev server directly: what errors do you have, what routes exist, what is in your logs. This tutorial sets it up, and then shows you what to actually DO with it.

The two "MCP things", disambiguated

People (me included) keep confusing two different pieces, so let us sort this out first:

• The MCP server built into next dev: since Next.js 16 your dev server exposes an MCP endpoint at http://localhost:3000/_next/mcp (the port follows your dev server). It is enabled by default, no flag needed (the experimental.mcpServer option from the Next.js 15 days is history). It exposes runtime diagnostic tools, on Next.js 16.3 that list is: get_errors, get_logs, get_routes, get_page_metadata, get_project_metadata, get_server_action_by_id, get_request_insights, plus the Turbopack only get_compilation_issues and compile_route. This endpoint only exists while next dev is running
• next-devtools-mcp (the npm package): this is the thing you register with your agent. Since version 0.4.0 it is a deliberately thin connector with only four tools: nextjs_index (discovers running dev servers, so nobody has to hardcode ports), nextjs_call (proxies calls to the built-in endpoint), nextjs_docs (points the agent at the version-matched docs bundled inside node_modules/next/dist/docs/) and browser_eval (points the agent at the agent-browser CLI for browser automation)

So: you register the package, you run the dev server, and the package connects the two. The docs and browser tools even work without a running dev server.

Setup for Claude Code CLI

Claude Code reads MCP servers from a .mcp.json file at the project root (project scope, so you can commit it to git and it works for every session in that repository). The quickest way is the claude mcp add command:

claude mcp add next-devtools --scope project -- cmd /c npx -y next-devtools-mcp@latest

Note the cmd /c part: that is the Windows gotcha. On Windows, npx is a npx.cmd batch file that can not be spawned directly by Claude Code, without the wrapper the server shows up in claude mcp list but never connects (spawn npx ENOENT). On macOS and Linux you drop the cmd /c.

The resulting .mcp.json:

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

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

Restart Claude Code (project scoped servers trigger a one-time approval prompt), then type /mcp to check the connection status, or run claude mcp list in the terminal to see a health check.

Setup for GitHub Copilot in VS Code

Copilot does NOT read .mcp.json, it has its own file: .vscode/mcp.json (note: no leading dot on the filename, the .vscode folder is already hidden). Two things are different from the Claude Code format and trip up every copy-paste: the root key is servers (not mcpServers) and every server needs an explicit type:

{
    "servers": {
        "next-devtools": {
            "type": "stdio",
            "command": "cmd",
            "args": ["/c", "npx", "-y", "next-devtools-mcp@latest"]
        }
    },
    "inputs": []
}

(Same cmd /c rule: drop it on macOS/Linux.) Then switch Copilot Chat to Agent mode, MCP tools are invisible in Ask and Edit modes. Click the tools icon below the prompt input to verify "next-devtools" is enabled.

Copilot also supports connecting directly to the built-in endpoint over HTTP, without the bridge (you lose port auto-discovery, docs and browser tools, but it is a nice fallback):

{
    "servers": {
        "nextjs-mcp": {
            "type": "http",
            "url": "http://localhost:3000/_next/mcp"
        }
    },
    "inputs": []
}

Things you can actually ask your agent to do

This is the fun part. All of the following prompts were verified against a real running project (Next.js 16.3.1, Turbopack, Windows) while writing this article, they are not theoretical.

Find errors without copy-pasting stack traces

use the nextjs mcp to check if my app has any errors

The agent calls get_errors (through nextjs_call) and receives a source-mapped answer. I planted a throw new Error('mcp verification test error') in a page, and this is what the agent got back:

{
    "sessionErrors": [{
        "url": "/mcp-test-error",
        "runtimeErrors": [{
            "errorName": "Error",
            "message": "mcp verification test error",
            "stack": [{ "file": "app\\mcp-test-error\\page.tsx", "methodName": "McpTestErrorPage", "line": 3, "column": 11 }]
        }]
    }]
}

Exact file, exact line, exact column. The agent goes straight to the bug.

Read the dev server logs

check the next.js dev server logs, are there any warnings or errors I should know about?

The agent calls get_logs, which returns the path to a structured log file (.next/dev/logs/next-development.log), and then reads it. Bonus that surprised me: the log does not only contain server output, browser console logs are forwarded into it too (each line is tagged with "source": "Server" or "source": "Browser"), so the agent sees your client-side console.log output without opening devtools.

List all routes

use the nextjs mcp and list all routes of my app

The agent calls get_routes and gets the complete live route table of the running app (in my case 100+ routes, including things you forget exist, like every opengraph-image route). Great before refactorings, or to ask follow-ups like "which of these routes have no metadata?".

Check for compilation issues (Turbopack)

use the nextjs mcp to check for compilation issues

Calls get_compilation_issues (Turbopack only), which returns current compiler diagnostics without you scrolling through the terminal. There is also compile_route to force-compile a route before visiting it.

Verify a page in a real browser

use the browser tools to open the homepage and check for console errors

The browser_eval tool does not drive a browser itself (that changed in 0.4.0 too): it detects the agent-browser CLI and hands your agent precise instructions to drive it (agent-browser open <url>, click, screenshot, ...). If agent-browser is not installed it tells the agent how to install it. Rendering a page in a real browser catches what curl never will: hydration errors, client-side exceptions, and (see above) it is what feeds get_errors.

Look things up in the version-matched docs

look up how cache components work, use the docs that match my installed next.js version

The nextjs_docs tool points the agent at the full Next.js documentation that ships inside node_modules/next/dist/docs/ since Next.js 16.2, matching your exact installed version. No more confidently wrong answers based on Next.js 14 training data.

Make sure the agent rules block is in your agent file

Since Next.js 16.3, next dev automatically writes (and keeps updated) a managed block in your AGENTS.md (or CLAUDE.md), pointing agents at those bundled docs. This is not MCP, it is a plain markdown mechanism, but it is the highest-leverage part of the whole setup: Vercel's own evals found that docs grounding via the agent file beats every other approach they tested.

Check that this block is present in your AGENTS.md or CLAUDE.md, and if you are on 16.2 (or the file got mangled), add it manually. On anything older than 16.2 there is no point in adding it, as the block points at bundled docs that do not exist yet in node_modules/next/dist/docs/, so on 16.0 or 16.1 you first need to upgrade:

<!-- BEGIN:nextjs-agent-rules -->
 
# This is NOT the Next.js you know
 
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
 
This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
 
<!-- END:nextjs-agent-rules -->

Commit it: next dev re-adds the block if it is missing, so deleting it from a diff only re-creates the uncommitted change forever.

What happened to the upgrade and cache components tools?

The previous version of this article showed /mcp.next-devtools.upgrade-nextjs-16 and /mcp.next-devtools.enable-cache-components. Both left the MCP server in 0.4.0 and are now distributed as agent skills instead (installable via npx skills, e.g. next-dev-loop or next-cache-components-optimizer). For version upgrades, the fastest path remains the codemod:

npx @next/codemod@latest upgrade

Congratulations 🎉 your agent can now interrogate your running Next.js app directly, instead of asking you to paste terminal output like it is 2024

If you liked this post, please consider buying me a coffee ☕ or sponsor ❤️ me on GitHub, as it will help me create more content and keep it free for everyone