How to Enable a Next.js MCP Server for Coding Agents

Direct answer: Next.js 16 and later can expose a running development server through its built-in MCP endpoint. Add the official next-devtools-mcp launcher to a project-root .mcp.json, start the dev server, and reload your coding agent.

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

The launcher discovers the running Next.js instance and forwards MCP tool calls to it. Next.js documents the built-in development endpoint as /_next/mcp. This is a development workflow, not unrestricted production access. See the official Next.js MCP guide.

Prerequisites

• Next.js 16 or later.
• An MCP-compatible coding agent.
• A development command such as pnpm dev.
• The repository opened at its root.

1. Confirm your Next.js version

pnpm next --version
# or
npm exec next -- --version

The documented MCP setup requires Next.js 16 or newer. For upgrade work, consult the Next.js 16 upgrade guide.

2. Create the project-root .mcp.json

Place this file beside package.json:

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

The filename and location matter. Keep the JSON valid and do not place it inside .next or an editor-specific directory.

3. Start the development server

pnpm dev
# npm run dev
# or yarn dev

Leave the process running. If it was already running when you created .mcp.json, stop and restart it so the launcher can discover the current instance.

4. Reload the coding agent

1. Open the repository root in your agent.
2. Reload its MCP configuration or restart the agent.
3. Look for next-devtools in the MCP or server panel.
4. Ask for current build errors or project metadata.

What the connection provides

Tool	Documented information
get_errors	Current build, runtime, and type errors.
get_logs	The development log path.
get_page_metadata	Route, component, and rendering information.
get_project_metadata	Project structure, configuration, and dev-server URL.
get_server_action_by_id	Source file and function name for a Server Action.
Live runtime and browser integration	Development inspection and browser-testing workflows described by Next.js.

These capabilities give an agent context from the development application. They do not replace deployment controls or expose a production server.

Add version-matched guidance with AGENTS.md

MCP exposes live application context. A root AGENTS.md tells the agent how to consult documentation matching the installed Next.js version. Next.js bundles those docs at node_modules/next/dist/docs/. The AI Coding Agents guide gives this example:

# Next.js instructions

Before any Next.js work, find and read the relevant doc in
`node_modules/next/dist/docs/`. Your training data is outdated —
the docs are the source of truth.

Claude Code, Cursor, and GitHub Copilot are named as examples of agents that automatically read AGENTS.md. If your agent uses CLAUDE.md, it can import the shared file with @AGENTS.md. The existing-project example in the guide uses Next.js v16.2.0-canary.37 or later; verify current requirements before adopting a canary version.

Configuration checklist

• Next.js is 16 or newer.
• .mcp.json is valid and at the project root.
• The entry invokes next-devtools-mcp@latest.
• The dev server is running and was restarted after configuration changes.
• The agent opened the same project root and reloaded MCP settings.
• AGENTS.md, if used, is also at the root.

Connection troubleshooting

No MCP tools appear

Cause: The agent did not load the file, the file is misplaced, or JSON is invalid. Fix: Validate the filename and JSON, reopen the repository at its root, and reload MCP settings.

The launcher cannot discover Next.js

Cause: The server is stopped, stale, or running Next.js 15 or earlier. Fix: Confirm the version, stop the process, run pnpm dev again, and reconnect.

Errors or routes are stale

Cause: You are connected to an old process or a rebuild has not completed. Fix: Restart the dev server, wait for its ready message, and request fresh metadata.

npx prompts or fails

Cause: The launcher arguments differ from the documented entry, or package installation is blocked. Fix: Use -y and next-devtools-mcp@latest, then run the same command manually to inspect the environment error.

AGENTS.md is ignored

Cause: The agent does not support that file, it is below the repository root, or it is not imported. Fix: Check the agent’s instruction-file rules and import it from CLAUDE.md when required.

Check the endpoint yourself

These commands check local reachability only. The MCP launcher still handles protocol discovery and tool forwarding.

curl -i http://localhost:3000/_next/mcp

import requests
r = requests.get("http://localhost:3000/_next/mcp", timeout=10)
print(r.status_code)
print(r.text[:500])

const res = await fetch('http://localhost:3000/_next/mcp');
console.log(res.status, (await res.text()).slice(0, 500));

A response confirms basic HTTP reachability, not that every agent loaded .mcp.json. Confirm the final connection with the agent’s MCP status and a tool request.

Performance, reliability, and cost

• Startup and rebuild time depend on your local machine and project.
• Restarting after configuration changes avoids ambiguity about which process was discovered.
• Keep the endpoint scoped to development; do not expose it as a public production interface.
• The cited documentation does not publish latency, uptime, or per-call pricing for this MCP connection.

Or skip the browser setup

If you need rendered page images rather than live Next.js diagnostics, ScreenshotNeo provides one HTTP request. Cookie banners, newsletter popups, and chat widgets are removed before capture. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000 shots.

See the ScreenshotNeo API docs for full-page capture, selectors, custom CSS and JavaScript, waits, blocking rules, device presets, PDFs, caching, signed links, async jobs, bulk capture, and usage reporting.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Create a free ScreenshotNeo account for 1,000 screenshots each month with no card.

FAQ

Does this work with Next.js 15?

The documented setup requires Next.js 16 or later.

Is /_next/mcp a production API?

No. It is described as an endpoint on the running development server.

Do MCP and AGENTS.md do the same thing?

No. MCP exposes live app context; AGENTS.md directs the agent to version-matched documentation.

Can several agents share the setup?

Yes, when they support the standard project-root .mcp.json format. Reload each agent separately.