Next.js 16.2 Agent DevTools: Debug AI Apps, MCP Servers, and Browser Logs Like a Pro (2026 Guide)

Next.js 16.2 landed on March 25, 2026, and it brings the most significant developer tooling update since the App Router migration. The headline features -- Agent DevTools, first-party MCP server integration, and Browser Log Forwarding -- are not incremental improvements. They represent Vercel's bet that AI-powered applications need fundamentally different debugging workflows than traditional web apps.

If you are building anything with AI in your Next.js stack -- whether that is an LLM-powered chatbot, an agentic workflow system, or a tool-calling interface backed by Model Context Protocol servers -- version 16.2 changes how you develop and debug those features.

This guide covers everything that shipped, how to set it up, and how to use it in practice.

What Shipped in Next.js 16.2

The 16.2 release focuses on three interconnected features that collectively form what Vercel calls the Agent DevTools suite. Each feature addresses a specific pain point that AI application developers have been dealing with since the AI SDK and MCP integrations became standard patterns in the Next.js ecosystem.

• Agent DevTools panel -- A dedicated tab in Next.js Dev Tools for inspecting AI agent behavior, tool calls, context windows, and token usage in real time
• next-devtools-mcp -- A built-in MCP server that exposes your development environment to AI coding assistants like Claude Code, Cursor, and Windsurf, giving them live access to your app's state, routes, errors, and logs
• Browser Log Forwarding -- Automatic forwarding of client-side console output, network errors, and React component state to both the Agent DevTools panel and connected MCP clients
• AGENTS.md convention -- A standardized file format that AI coding assistants read to understand your project's architecture, conventions, and constraints before generating code

These features are available immediately by updating to next@16.2.0. No additional packages are required for the core Agent DevTools panel. The MCP server requires a one-time configuration step covered below.

Agent DevTools Deep Dive

The Agent DevTools panel appears as a new tab alongside the existing Components, Profiler, and Network tabs in the Next.js Dev Tools overlay. It provides real-time visibility into every AI-related operation happening in your application.

What You Can Inspect

The panel displays a chronological stream of AI events with full drill-down capability:

• LLM calls -- Every call to generateText, streamText, generateObject, or streamObject from the Vercel AI SDK, including the full prompt, system message, model parameters, response tokens, and latency
• Tool invocations -- Each tool call made by an AI agent, showing the tool name, input parameters, execution duration, and returned result. Failed tool calls are highlighted with the error stack trace
• Context window visualization -- A token-level breakdown of what is being sent to the model on each request. This is invaluable for debugging context window overflow issues that cause truncated or degraded responses
• Streaming state -- For streamed responses, a real-time view of chunks as they arrive, including any backpressure or buffering issues between the server and client
• MCP server communication -- Every message exchanged between your app and connected MCP servers, with protocol-level detail for debugging connection and serialization issues

Filtering and Search

The panel includes filters for event type, status (success, error, pending), model provider, and time range. A full-text search across prompts, tool names, and error messages lets you find specific interactions quickly -- essential when debugging complex multi-step agent workflows that generate dozens of events per user action.

Enabling Agent DevTools

Agent DevTools are enabled by default in development mode starting with 16.2. No configuration is needed. If you have previously disabled the Dev Tools overlay, re-enable it in your next.config.ts:

// next.config.ts
import type { NextConfig } from 'next'

const config: NextConfig = {
  devIndicators: {
    position: 'bottom-right',
  },
  // Agent DevTools are part of the dev overlay
  // They activate automatically when AI SDK usage is detected
}

export default config

Setting Up next-devtools-mcp

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 exports
• getErrors -- Returns current build errors, runtime errors, and hydration mismatches with full stack traces and source locations
• getLogs -- Returns recent server-side and forwarded browser logs, filtered by level
• getComponentTree -- Returns the React component hierarchy for the current page, including server and client component boundaries
• getNetworkRequests -- Returns recent fetch calls, API route invocations, and external API requests with timing data
• getAIEvents -- 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.

Step 1: Open Agent DevTools

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.

Step 2: Inspect the Tool Call

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