Source URL: https://nextjs.org/docs/app/guides/mcp

Enabling Next.js MCP Server for Coding Agents

The Model Context Protocol (MCP) is an open standard that allows AI agents and coding assistants to interact with your applications through a standardized interface.

Next.js 16+ includes MCP support that enables coding agents to access your application’s internals in real-time. To use this functionality, install the next-devtools-mcp package.

Getting started

Requirements: Next.js 16 or above

Add next-devtools-mcp to the .mcp.json file at the root of your project:

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

That’s it! When you start your development server, next-devtools-mcp will automatically discover and connect to your running Next.js instance.

For more configuration options, see the next-devtools-mcp repository.

Capabilities

next-devtools-mcp provides coding agents with a growing set of capabilities:

Application Runtime Access

Error Detection: Retrieve current build errors, runtime errors, and type errors from your dev server
Live State Queries: Access real-time application state and runtime information
Page Metadata: Query page routes, components, and rendering details
Server Actions: Inspect Server Actions and component hierarchies
Development Logs: Access development server logs and console output

Development Tools

Next.js Knowledge Base: Query comprehensive Next.js documentation and best practices
Migration and Upgrade Tools: Automated helpers for upgrading to Next.js 16 with codemods
Cache Components Guide: Setup and configuration assistance for Cache Components
Browser Testing: Playwright MCP integration for verifying pages in the browser

Note: The Next.js team is actively expanding these capabilities. New tools and features are added regularly to improve the agent development experience.

Development workflow

Start your Next.js development server:

pnpm dev

npm run dev

yarn dev

bun dev

Your Coding Agent will automatically connect to the running Next.js instance via next-devtools-mcp
Open your application in the browser to view pages
Query your agent for insights and diagnostics (see examples below)

Available tools

Through next-devtools-mcp, agents can use the following tools:

get_errors: Retrieve current build errors, runtime errors, and type errors from your dev server
get_logs: Get the path to the 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_server_action_by_id: Look up Server Actions by their ID to find the source file and function name

Using with agents

MCP-compatible Coding Agents can automatically discover and connect to your Next.js development server, providing them with rich context about your project.

Benefits for agent-assisted development

Agents can:

Make context-aware suggestions: Recommend the right place to add new features based on your existing structure
Query live application state: Check current configuration, routes, and middleware during development
Understand your app router pages layout: Know exactly which page and layout are rendered
Provide accurate implementations: Generate code that follows your project’s patterns and conventions

Examples

Error detection and diagnosis

Ask your agent about errors in real-time:

User: "What errors are currently in my application?"

The agent will:

Query your running Next.js application via next-devtools-mcp
Retrieve current build errors, runtime errors, and type errors
Analyze the errors and provide actionable fixes

Agent response (click to expand)

> fix errors on the page

⏺ I'll help you fix the errors on the page. Let me first check what errors exist by looking at the
  current state of the project.

⏺ next-devtools - nextjs_runtime (MCP)(action: "discover_servers")
⏺ next-devtools - nextjs_runtime (MCP)(action: "call_tool", toolName: "get_errors")

⏺ I found a hydration error on the /about page. The error shows that the server is rendering
  "server" but the client is rendering "client", causing a mismatch. Let me create a todo list and fix
   this issue.

⏺ Perfect! Now let me check for errors on the page.           01:14 PM  claude-sonnet-4-5-20250929

⏺ next-devtools - nextjs_runtime (MCP)(action: "call_tool", toolName: "get_errors")
  ⎿ {
      "success": true,
      "port": 3000,
      "toolName": "get_errors",
      "result": {
        "content": [
          {
            "type": "text",
            "text": "# Found errors in 1 browser session(s)\n\n## Session: /about\n\n**1 error(s)
     found**\n\n### Runtime Errors\n\n#### Error 1 (Type: recoverable)\n\n**Error**: Hydration failed

Upgrading and best practices

Get help with Next.js concepts and migrations:

User: "Help me upgrade my Next.js app to version 16"

The agent will analyze your current version, guide you through automated migrations with codemods, and provide step-by-step instructions for handling breaking changes.

Ask conceptual questions:

User: "When should I use 'use client' in App Router?"

The agent will query the Next.js knowledge base and provide documentation-backed explanations with examples from your codebase.

How it works

Next.js 16+ includes a built-in MCP endpoint at /_next/mcp that runs within your 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 Next.js dev server
Provide a unified interface for coding agents

This architecture decouples the agent interface from the internal implementation, enabling next-devtools-mcp to work seamlessly across different Next.js projects.

Troubleshooting

MCP server not connecting

Ensure you’re using Next.js v16 or above
Verify next-devtools-mcp is configured in your .mcp.json
Start your development server: npm run dev
Restart your development server if it was already running
Check that your coding agent has loaded the MCP server configuration