vercel/next.js / docs / 01-app / 02-guides / mcp.mdx

---

title: Connecting coding agents to the Next.js MCP server nav_title: Next.js MCP Server description: Learn how to give coding agents access to your running Next.js app through the built-in MCP endpoint. related: links: - app/guides/ai-agents

The Model Context Protocol (MCP) is an open standard that lets AI agents and coding assistants interact with your applications through one shared interface.

In Next.js 16 and later, the development server exposes an MCP endpoint at /_next/mcp. It gives coding agents the running app's view of errors, routes, logs, and compilation issues. To connect your agent client to it, install the next-devtools-mcp package.

Skills such as next-dev-loop call /_next/mcp directly, so they work without this setup.

Getting started

Install next-devtools-mcp for the coding agents on your machine with add-mcp:

npx add-mcp next-devtools-mcp@latest

Or add it to the .mcp.json file at the root of your project:

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

When you start your development server, next-devtools-mcp discovers and connects to the running Next.js instance. For client-specific setup, see the next-devtools-mcp repository.

Capabilities

next-devtools-mcp connects your agent client to the Next.js development server. It gives agents these tools:

• nextjs_index: Discovers running Next.js dev servers and lists the runtime tools each one exposes.
• nextjs_call: Calls a runtime tool on a discovered dev server.
• nextjs_docs: Points the agent at the version-matched docs bundled with your installed Next.js in node_modules/next/dist/docs/.
• browser_eval: Points the agent at the agent-browser CLI for verifying pages in a real browser.

nextjs_docs and browser_eval don't do the work themselves. They tell the agent where the docs are or how to run the CLI, and the agent uses them directly.

Runtime tools

Through nextjs_call, agents can use the tools the Next.js development server exposes at /_next/mcp:

• get_errors: Get the current error state, including Next.js global errors such as next.config validation, browser runtime errors, and build errors with source-mapped stack traces.
• get_logs: Get the path to the development log file, which contains browser console logs and server output.
• get_page_metadata: Get runtime metadata about what contributes to the current page render. Requires the page to be open in a browser.
• get_project_metadata: Get the project path and dev server URL.
• get_routes: Get all routes that will become entry points by scanning the filesystem. Returns routes grouped by router type (appRouter, pagesRouter). Dynamic segments appear as [param] or [...slug] patterns.
• get_server_action_by_id: Look up a Server Action by its ID to find its source file and export name.
• get_compilation_issues: Build the module graph for all routes and return compilation issues such as resolve errors, missing modules, and transform errors. Doesn't require a browser session. Turbopack only.
• compile_route: Compile a specific route without making an HTTP request to it. Accepts either a routeSpecifier (for example, /blog/[slug], as returned by get_routes) or a path (for example, /blog/hello-world), which is resolved to the matching route. Returns any compilation issues for the route. Turbopack only.
• get_request_insights: Get recent App Router request timelines, server fetches, and cache behavior captured by the local span recorder. Requires experimental.requestInsights.

With the compilation tools, agents can check whether code compiles from the running dev server instead of running next build while they are still editing.

Development workflow

1. Start your Next.js development server:

pnpm dev

npm run dev

yarn dev

bun dev

2. Your coding agent connects to the running Next.js instance through next-devtools-mcp.

3. Open the pages you're working on in the browser. Tools such as get_errors and get_page_metadata read from active browser sessions.

4. Ask your agent about the running app, as in the examples below.

Examples

Error detection and diagnosis

Ask your agent about errors in the running app:

What errors are currently in my application?

The agent will:

• Discover the running dev server with nextjs_index
• Call get_errors through nextjs_call to retrieve the current errors
• Analyze the errors and suggest fixes

<details> <summary>Agent response (click to expand)</summary>

> fix errors on the page

⏺ I'll check which errors the running app reports before changing anything.

⏺ next-devtools - nextjs_index (MCP)
⏺ next-devtools - nextjs_call (MCP)(port: 3000, toolName: "get_errors")
  ⎿ # Found errors in 1 browser session(s)

    ## Session: /about

    **1 error(s) found**

    ### Runtime Errors

    #### Error 1 (Type: recoverable)

    **Error**: Hydration failed because the server rendered text didn't match the client.

⏺ The /about page renders "server" on the server and "client" in the browser,
  which causes a hydration mismatch. I'll fix the component and check again.

</details>

Concepts and best practices

Ask conceptual questions:

When should I use 'use client' in the App Router?

The agent reads the version-matched Next.js docs bundled with your project and answers with examples from your codebase.

How it works

The Next.js 16+ development server runs a built-in MCP endpoint at /_next/mcp. The next-devtools-mcp package discovers these endpoints and communicates with them, so it can:

• Connect to multiple Next.js instances running on different ports
• Forward tool calls to the right Next.js dev server
• Give agents one set of tools for every instance

Agents that connect through next-devtools-mcp use the same setup across Next.js projects and versions.

The endpoint is enabled by default. To disable it, set experimental.mcpServer to false in next.config.

Troubleshooting

MCP server not connecting

• Use Next.js 16 or later
• Verify next-devtools-mcp is configured in your agent client, for example in .mcp.json
• Check that experimental.mcpServer is not set to false in next.config
• Start your development server with npm run dev, or restart it if it was already running
• Check that your coding agent has loaded the MCP server configuration