The next-devtools-mcp server is the feature with the most immediate productivity impact. It turns your running Next.js dev server into an MCP server that AI coding assistants can connect to — giving them live context about your application’s state, errors, routes, and component tree.
Instead of copying error messages into your AI assistant and describing what you see on screen, the assistant reads your application state directly. It sees the same errors, the same component hierarchy, the same network requests you see in your browser.
Installation and Configuration
The MCP server ships as part of the next package — no separate installation needed. Start it alongside your dev server:
# Start the dev server with MCP enabled
npx next dev --mcp
# Or add it to your package.json scripts
{
"scripts": {
"dev": "next dev",
"dev:mcp": "next dev --mcp"
}
}
When launched with the --mcp flag, Next.js starts a stdio-based MCP server on the same process. The server exposes the following tools to connected clients:
getRoutes — Returns all registered routes with their type (page, API, middleware), parameters, and metadata exportsgetErrors — Returns current build errors, runtime errors, and hydration mismatches with full stack traces and source locationsgetLogs — Returns recent server-side and forwarded browser logs, filtered by levelgetComponentTree — Returns the React component hierarchy for the current page, including server and client component boundariesgetNetworkRequests — Returns recent fetch calls, API route invocations, and external API requests with timing datagetAIEvents — Returns the same AI event stream visible in the Agent DevTools panel, accessible programmatically by coding assistants
Connecting Claude Code
To connect Claude Code to your running Next.js MCP server, add the following to your project’s .mcp.json file:
{
"mcpServers": {
"next-devtools": {
"command": "npx",
"args": ["next", "dev", "--mcp"],
"env": {
"NODE_ENV": "development"
}
}
}
}
Once connected, Claude Code can query your application state directly. Ask it to “check for errors in my Next.js app” and it will call the getErrors tool and respond with specific, contextualized fixes based on your actual error output — not generic suggestions based on the error message alone.
Connecting Cursor and Windsurf
Both Cursor and Windsurf support MCP servers through their settings panels. Add the same server configuration in your editor’s MCP settings. The connection uses stdio transport, so no port configuration or network setup is required.
Browser Log Forwarding
Browser Log Forwarding solves a problem that has plagued full-stack debugging since server components were introduced: client-side errors and logs are invisible to server-side tooling. When a hydration mismatch occurs, when a client component throws, or when a fetch call fails in the browser, that information exists only in the browser console — disconnected from your server logs and invisible to MCP-connected coding assistants.
With 16.2, client-side logs are automatically forwarded to the dev server and made available through both the Agent DevTools panel and the MCP server’s getLogs tool.
What Gets Forwarded
- All
console.log, console.warn, console.error, and console.info calls
- Unhandled promise rejections and uncaught exceptions
- React error boundary catches with component stack traces
- Failed network requests (fetch errors, 4xx/5xx responses) with request details
- Hydration mismatch warnings with the specific DOM diff
Configuration
Browser Log Forwarding is enabled by default in development. You can customize what gets forwarded in next.config.ts:
// next.config.ts
import type { NextConfig } from 'next'
const config: NextConfig = {
devtools: {
browserLogForwarding: {
enabled: true,
levels: ['error', 'warn', 'info'], // omit 'log' to reduce noise
forwardNetworkErrors: true,
forwardHydrationWarnings: true,
},
},
}
export default config
In production, Browser Log Forwarding is disabled entirely. No client-side data is sent to any server. The feature exists exclusively for development-time debugging.
The AGENTS.md Convention
The AGENTS.md file is not a new idea — projects have used README files and documentation to onboard developers for decades. What 16.2 formalizes is a machine-readable convention that AI coding assistants are trained to look for and parse before generating code for your project.
When an AI assistant connected via MCP (or reading your repository directly) encounters an AGENTS.md file, it uses that information to constrain and guide its code generation. This reduces the most common frustration with AI coding tools: generating code that works in isolation but violates your project’s specific patterns, conventions, or architectural decisions.
What to Include
An effective AGENTS.md for a Next.js project should cover:
# AGENTS.md
## Architecture
- App Router with Server Components by default
- Client components only in files suffixed with 'Client.tsx'
- All data fetching in Server Components or Server Actions
## Conventions
- Tailwind CSS v4 with custom design tokens in globals.css
- Zod for all runtime validation
- Named exports for components (except page.tsx default exports)
- No console.log in committed code
## Key Patterns
- Tool pages: server page.tsx exports metadata, imports ToolClient.tsx
- API routes return NextResponse with consistent error shapes
- Use existing UI components in src/components/ui/ -- do not recreate
## Forbidden
- No 'any' types
- No inline styles
- No shadcn/ui (custom component system)
- No default exports for non-page components
The key principle: be specific about what makes your project different from a default Next.js setup. Generic advice like “write clean code” adds no value. Specific constraints like “all forms use react-hook-form with Zod resolvers” directly improve the quality of AI-generated code for your project.
Nested AGENTS.md Files
You can place AGENTS.md files in subdirectories to provide context specific to that part of your codebase. An AGENTS.md in your src/components/ directory can specify component patterns, while one in src/lib/ can describe utility function conventions. AI assistants merge these with the root-level file, with more specific files taking precedence.
Practical Tutorial: Debugging an AI Chat App
Here is a concrete workflow showing how these features work together when debugging a real issue in an AI-powered chat application.
Scenario
Your chat app uses the Vercel AI SDK with a tool-calling agent that can search a knowledge base and generate citations. Users report that the agent sometimes returns empty citations — the tool is called but returns no results even when relevant documents exist.
Navigate to the chat page in your browser and open the Agent DevTools panel. Reproduce the issue by asking a question you know should return citations. In the Agent DevTools stream, you can see the full sequence: the LLM call, the tool invocation for searchKnowledgeBase, and the tool’s response.
Click the searchKnowledgeBase tool invocation in the timeline. The detail view shows the input parameters the model sent and the response the tool returned. You notice the model is sending a query parameter with excessive detail — a three-sentence paraphrase instead of concise search keywords. Your vector search is returning zero results because the query is too long and specific.
Step 3: Check with MCP
Switch to Claude Code (connected via next-devtools-mcp) and ask it to review the searchKnowledgeBase tool definition. It pulls the tool schema from your running app via the getAIEvents tool and identifies that the tool’s parameter description says “the user’s question” instead of “concise search keywords extracted from the user’s question.” The model is following the tool description literally.
Step 4: Fix and Verify
Update the tool description to be more precise. Reproduce the query. The Agent DevTools panel now shows a concise keyword query going to the search tool, and citations return correctly. The Browser Log Forwarding confirms no client-side errors during the updated flow.
Total debugging time: under five minutes, with full visibility into every layer of the AI interaction. Without Agent DevTools, this same issue would require adding temporary logging, restarting the server, parsing raw JSON responses, and guessing at what the model was doing internally.
Getting Started Today
Update to Next.js 16.2, add an AGENTS.md file to your project root, and start your dev server with the --mcp flag. The tooling works immediately with zero configuration beyond that.
For teams building production AI applications on Next.js, these tools eliminate the single biggest time sink in AI development: the opacity of agent behavior. When you can see exactly what your AI is doing, why it made a specific tool call, and what data it received back, you debug in minutes instead of hours.
Building AI-powered apps with Next.js? Our Next.js starter templates at wowhow.cloud ship with AGENTS.md pre-configured, AI SDK integration patterns, MCP server setup, and production-ready tool-calling architectures. Skip the boilerplate and start building features on day one.
Blog reader exclusive: Use code BLOGREADER20 for 20% off your entire cart.
Browse Next.js Starter Templates
Comments · 0
Beta: comments are stored locally on your device and not visible to other readers.
No comments yet. Be the first to share your thoughts.