Next.js AGENTS.md + MCP: Agents Read Real Docs [2026]

Answer in 50 Words

Next.js ships version-matched docs inside the next package plus an AGENTS.md convention that points coding agents at real APIs instead of training data. My Junagadh setup holds TTFB 60ms, cut deploy-time API mistakes 40%, and pairs with the Next.js MCP server for live app state. Setup and wiring below.

I run SaaS Next from Junagadh, Gujarat. My Next.js 16.3 front for a Rajkot dealer catalog serves 9,400 SKUs with cached reads at 60–90ms TTFB. Before AGENTS.md, every agent-assisted change carried the same tax: the agent invented a prop, guessed a route convention, or imported a function removed two minors ago. I fixed each one by hand. The bundled-docs convention plus the MCP server removed most of that rework. Here is the exact setup I run.

War Story 1: The Deleted API That Shipped

July afternoon, 16:40. I asked an agent to add dealer-wise stock filters to the catalog page. It wrote clean code against an App Router caching API from its training cutoff. That API had changed two releases earlier. Build passed. Production threw at runtime for dealers with empty filter sets — 340 errors in an hour before my alert fired. I rolled back, pinned the correct API from the installed package docs, and re-shipped at 19:20. Lost half a day plus a dealer apology call.

Root cause was not the agent. It was missing context. The right docs sat inside node_modules/next/dist/docs/ matching my installed version. The agent never read them because nothing told it to. AGENTS.md fixes that with one instruction file at the repo root.

War Story 2: The Guessed Column That Cost ₹18K

Different week, same pattern on the Laravel side before I wired MCP. An agent wrote a stock-adjust mutation against a quantity column. Real column: sellable_qty. Staging caught it. Had it reached production, the adjustment would have silently written to a nullable legacy column while the storefront read the real one — overselling during a weekend sale. My Rajkot client estimated the exposure at ₹18K in courier reversals. That incident is why I now give agents structured access (MCP tools, version-matched docs) instead of letting them infer schema from file names.

What AGENTS.md Actually Does

Source: Next.js docs, App Router guides on AI agents (verified Sep 2026). When you install next, version-matched documentation ships at node_modules/next/dist/docs/, mirroring the public docs structure — guides, API references, file conventions for App and Pages Router. An AGENTS.md file at the project root tells agents to read those bundled docs before writing code. Claude Code, Cursor, and Copilot-class tools pick it up automatically at session start. create-next-app generates AGENTS.md and CLAUDE.md for new projects. On 16.1 and earlier, a codemod generates the files and outputs bundled docs to .next-docs/.

The instruction is intentionally minimal: read the bundled docs first. That single redirect beats any prompt-engineering trick I tried. My deploy-time API mistakes dropped 40% across 60 agent-assisted changes measured over five weeks (15 mistakes before, 9 after — small sample, consistent direction).

Setup for 16.2 canary 37 and later:

# verify bundled docs exist for your installed version
ls node_modules/next/dist/docs | head
node -e "console.log(require('next/package.json').version)"

# scaffold agent files on older trees
npx @next/codemod@canary add-agents-md
ls AGENTS.md CLAUDE.md

<!-- AGENTS.md (what I actually keep) -->
# Agent instructions

Before writing any Next.js code, read the version-matched docs in
`node_modules/next/dist/docs/` (fallback `.next-docs/` on 16.1 and earlier).
Match the installed `next` version exactly. Prefer App Router conventions in
these docs over training data. After code changes, run `npm run build` and
paste the first failing block verbatim before proposing fixes.

That last line matters. Agents that paste the exact build error fix things twice as fast in my runs because they stop paraphrasing errors into wrong searches.

The MCP Server: From Docs to Live State

Bundled docs answer "what does this version support." The Next.js MCP server answers "what is this app doing right now." Per the docs, it exposes application state to coding agents — routes, errors, runtime context — so the agent inspects instead of assuming. My loop with the community nextjs-agent-mcp pattern (route map + dev-error capture + in-page bridge) looks like this: agent claims a tab, snapshots the page model, fills the form, waits for the selector, then reads network calls and console output to verify. No Playwright install in my case — plain Node plus the bridge component mounted dev-only.

Wiring I use in development:

// components/agent-bridge.tsx ('use client', dev only)
'use client';
import { useEffect } from 'react';

export function AgentBridge() {
  useEffect(() => {
    if (process.env.NODE_ENV !== 'development') return;
    const port = process.env.NEXT_PUBLIC_AGENT_BRIDGE_PORT ?? '7333';
    // connects the open tab to the local broker; renders HUD bottom-right
    void import('../lib/agent-bridge-client').then(m => m.connect(port));
  }, []);
  if (process.env.NODE_ENV !== 'development') return null;
  return null;
}

Rules I enforce: bridge mounts dev-only, never production. One agent owns one tab at a time. Every run ends with release_tab. Screenshots stay in-page and best-effort. The agent loop is claim → snapshot → act → wait → verify via network + console → release. Anything that skips verification gets its change reverted in review.

Measured Effects: Junagadh Ledger

No speed miracle. The win is fewer wrong merges and faster fixes. For an SME paying per change, that is real money: six fewer broken deploys in five weeks at ~45 minutes saved each is a full working day returned. On the API side the same dealer stack (Postgres + Valkey behind Docker, P95 latency 120ms on catalog reads, API key scoped per dealer) stayed untouched — this change is purely about what the agent reads before it writes.

When NOT to Use This

Direct talk: if your repo pins next below 16.1 and you cannot run the codemod cleanly, skip the bundled-docs path until you upgrade — pointing agents at mismatched docs is worse than no pointer. If your team never uses agents for code changes, AGENTS.md adds nothing; the MCP bridge also stays parked. And if your app has 5 routes and one form, the bridge ceremony (claim, snapshot, verify) costs more than it saves. I wire the full loop only on catalog-scale apps with real forms, lists, and auth states.

Frequently Asked Questions

Does AGENTS.md work with Cursor, Claude Code, and Copilot?

Yes. All three read AGENTS.md at session start in my runs. create-next-app also emits CLAUDE.md importing the same instructions for Claude users. Keep the file short — one directive pointing at bundled docs plus the build-and-paste-error rule beats a long style essay agents ignore.

Where do version-matched docs live?

Inside node_modules/next/dist/docs/ for current releases, mirroring the public site structure. On 16.1 and earlier the codemod writes them to .next-docs/ instead. I check the installed next version first, then confirm the docs path exists before telling any agent to use it.

Do I still need the MCP server if I have AGENTS.md?

They solve different halves. Bundled docs give correct APIs for your version. The MCP server gives live app state — routes, errors, storage, network. Docs prevent wrong code. The bridge catches wrong behavior. I run both on catalog apps, docs-only on small sites.

What does this setup cost for a Gujarat SME?

I quote ₹55K–₹85K for a Next.js SSR build depending on catalog size and auth scope; the AGENTS.md + MCP wiring is inside that, roughly a half-day. Infra stays at my standard ₹6,200/month VPS. The return shows up as fewer broken deploys — six avoided in five weeks on my own repo.

Bottom Line

Point agents at truth: version-matched docs for APIs, the MCP server for live state. My Junagadh numbers read 40% fewer deploy-time API mistakes and fixes in 26 minutes instead of 48, with TTFB steady at 60ms. Half a day to wire, nothing extra on the monthly bill. If agents touch your Next.js repo, add the file this week.

Relevant links: web development for Next.js SSR builds, AI development for agent + MCP scoping, automation notes for n8n wiring, selected work, and contact for the same setup on your repo.