ai agents

30 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Next.js MCP Server setup and requirements

Next.js 16 or above includes built-in Model Context Protocol (MCP) support. To use MCP functionality, install the next-devtools-mcp package and add it to a .mcp.json file at the root of your project with the configuration: {"mcpServers": {"next-devtools": {"command": "npx", "args": ["-y", "next-devtools-mcp@latest"]}}}. When the development server starts, next-devtools-mcp automatically discovers and connects to the running Next.js instance.

MCP server capabilities for coding agents

The next-devtools-mcp package provides coding agents with: Application Runtime Access (Error Detection, Live State Queries, Page Metadata, Server Actions inspection, Development Logs), Development Tools (Documentation Gateway pointing to version-accurate docs in node_modules/next/dist/docs/, Playwright MCP integration for browser testing).

MCP tools available to coding agents

The following tools are available through next-devtools-mcp: get_errors (retrieve current build errors, runtime errors, and type errors from dev server), get_logs (get path to development log file containing browser console logs and server output), get_page_metadata (get metadata about specific pages including routes, components, and rendering information), get_project_metadata (retrieve project structure, configuration, and dev server URL), get_routes (get all routes grouped by router type; dynamic segments appear as [param] or [...slug] patterns), get_server_action_by_id (look up Server Actions by ID to find source file and function name), get_compilation_issues (retrieve compilation warnings and errors from bundler, Turbopack only), compile_route (trigger on-demand compilation of a specific route by routeSpecifier or path, returns compilation issues, Turbopack only).

MCP development workflow steps

To use MCP with coding agents: 1) Start the Next.js development server using pnpm dev, npm run dev, yarn dev, or bun dev. 2) The Coding Agent will automatically connect to the running Next.js instance via next-devtools-mcp. 3) Open your application in the browser to view pages. 4) Query your agent for insights and diagnostics.

How MCP endpoints work in Next.js

Next.js 16+ includes a built-in MCP endpoint at /_next/mcp that runs within the development server. The next-devtools-mcp package automatically discovers and communicates with these endpoints, allowing it to connect to multiple Next.js instances running on different ports, forward tool calls to the appropriate dev server, and provide a unified interface for coding agents.

MCP troubleshooting checklist

If the MCP server is not connecting: ensure you are using Next.js v16 or above, verify next-devtools-mcp is configured in .mcp.json, start your development server with npm run dev, restart your development server if it was already running, and check that your coding agent has loaded the MCP server configuration.

Benefits of MCP for agent-assisted development

When connected via MCP, coding agents can make context-aware suggestions for where to add new features based on existing structure, query live application state to check current configuration and routes during development, understand the app router pages layout to know exactly which page and layout are rendered, and provide accurate implementations by generating code that follows your project's patterns and conventions.

agents-md codemod for AI agent documentation setup

Run 'npx @next/codemod@canary agents-md' to set up AI agent documentation before upgrading. After upgrading, verify AGENTS.md points at the docs for the installed Next.js version. On Next.js 16.2 and later, this should be the bundled docs in node_modules/next/dist/docs/.

Bundled Next.js docs location in node_modules

Next.js ships version-matched documentation inside the next package at node_modules/next/dist/docs/. This directory mirrors the structure of the Next.js documentation site, with subdirectories for 01-app (containing getting-started, guides, and api-reference), 02-pages, 03-architecture, and an index.mdx file at the root.

AGENTS.md auto-generation on Next.js 16.3+

On Next.js 16.3 or later, running next dev automatically generates AGENTS.md and CLAUDE.md at the project root if an AI coding agent is detected in the environment and no managed block is present. Existing files are upserted with content outside the managed block preserved. The managed block is delimited by  and  markers.

create-next-app generates AGENTS.md automatically

The create-next-app command generates AGENTS.md and CLAUDE.md automatically in new projects. To skip generation, pass the --no-agents-md flag.

Disable agent rules in next.config.ts

To opt out of AGENTS.md auto-generation, set agentRules to false in next.config.ts: import type { NextConfig } from 'next'; const nextConfig: NextConfig = { agentRules: false, }; export default nextConfig

Next.js 16.2 docs bundling without auto-generation

On Next.js version 16.2, the docs are bundled at node_modules/next/dist/docs/ but AGENTS.md is not auto-generated. You must add the AGENTS.md file manually with instructions to read the bundled docs before writing code.

Legacy agents-md command for Next.js 16.1 and earlier

On Next.js 16.1 and earlier, the docs are not bundled. Use the legacy command 'npx @next/codemod@canary agents-md' which downloads a version-matched copy to .next-docs/ in the project root and indexes it in AGENTS.md.

Network access to Next.js docs with Markdown format

The Next.js docs are available over the network by appending .md to any page URL on nextjs.org/docs for plain Markdown. Clients sending an Accept: text/markdown header also receive Markdown. Per-error pages under /docs/messages are available this way but not bundled. The index at /docs/llms.txt and single-file /docs/llms-full.txt follow the llms.txt convention for agent discovery.

MCP server for agent runtime visibility

The Next.js MCP server at /_next/mcp exposes the running dev server's routes, server logs, and compilation issues. It provides get_compilation_issues and compile_route tools that report whether code compiles from the dev server without requiring a full next build.

Browser console forwarding to terminal

The next dev command forwards browser console errors and warnings to the terminal through the logging.browserToTerminal config, so output agents read includes client-side failures they are asked to fix.

Dev server PID and port tracking in .next/dev/lock

The next dev command writes its PID, port, and URL to .next/dev/lock. When starting a second next dev in the same project, it prints the running server's URL and the PID to kill, allowing an agent to connect to the existing server instead of starting a duplicate.

agent-browser CLI for DOM and console inspection

agent-browser is a CLI that exposes the DOM, console, network, and Web Vitals as structured text. With React DevTools enabled (via --enable react-devtools flag), it reports the component tree and which Suspense boundaries are pending, allowing an agent to run commands like 'react tree' and inspect output instead of viewing a DevTools panel.

Error-driven fixes with labeled options in Cache Components

With Cache Components enabled, a blocking error presents labeled fixes, each making a different trade-off. The dev overlay adds a Copy prompt button that packages the chosen fix into a paste-ready prompt, walking the agent through reading the error page, applying the canonical pattern, and verifying the result at runtime.

Error menu in terminal and CI logs

The same error fix menu that appears in the dev overlay prints in the next dev terminal and in next build output, so an agent reading CI logs sees the labeled fixes and Learn more links.

Debug prerendering with server source maps

When a production build minifies server code, use next build --debug-prerender to turn on server source maps and continue past the first failure, providing agents with enough information beyond the build error alone.

Per-error pages for agent guidance

Per-error pages under /docs/messages are written for agents to read. Each page follows the same shape with canonical patterns for every fix, trade-offs against other fixes, and gotchas agents are likely to miss on a first attempt.

Skills for multi-step workflows

Next.js Skills package multi-step workflows as structured instructions an agent installs and follows, such as adopting Cache Components or Partial Prefetching across an app. Framework knowledge comes from the bundled docs, not from Skills, as always-available context outperforms on-demand retrieval.

Three workflow types for Next.js Skills

Next.js Skills serve three workflow types: runtime foundations like next-dev-loop that give any coding task a repeatable inspect, edit, and verify cycle; interactive workflows that make broader changes with user checkpoints such as adopting Cache Components; and unattended loops that work toward a verifiable goal and stop only for genuine decisions.

next-dev-loop skill installation and usage

The next-dev-loop runtime foundation skill is installed with 'npx skills add vercel/next.js --skill next-dev-loop'. It verifies changes against a running dev server using the MCP server and browser. After using this skill, instruct the agent to verify the page still works at runtime using the next-dev-loop Skill after every edit.

next-cache-components-adoption skill

The next-cache-components-adoption Skill migrates an app to Cache Components in three steps: turns the flag on and finds routes that cannot prerender; fixes them one feature at a time with user checkpoints; confirms each feature against next dev and next build before moving on. Install with 'npx skills add vercel/next.js --skill next-cache-components-adoption'.

next-cache-components-optimizer skill

The next-cache-components-optimizer Skill takes a target route and works toward specific UI at click time by: writing a failing instant() test for the named UI; refactoring the route until it passes, often by moving a data read below a Suspense boundary; committing the passing test with the refactoring to catch regressions. Requires a route that already builds with Cache Components. Install with 'npx skills add vercel/next.js --skill next-cache-components-optimizer'.

next-partial-prefetching-adoption skill

The next-partial-prefetching-adoption Skill moves an app onto Partial Prefetching in three steps: audits existing Link prefetch={true} calls with user input; turns the flag on and resolves insights; marks routes whose URL data might be worth prefetching. Requires Cache Components already adopted. Install with 'npx skills add vercel/next.js --skill next-partial-prefetching-adoption'.

CLAUDE.md file references AGENTS.md

The CLAUDE.md file generated automatically contains a single line '@AGENTS.md' that references the AGENTS.md file. Custom project-specific instructions can be added outside the managed block markers in AGENTS.md and are preserved when Next.js updates the managed block.

Give your agent this brain