1# Debug Tricks
2 
3Tricks to speed up debugging Next.js applications.
4 
5## MCP Endpoint (Dev Server)
6 
7Next.js exposes a `/_next/mcp` endpoint in development for AI-assisted debugging via MCP (Model Context Protocol).
8 
9- **Next.js 16+**: Enabled by default, use `next-devtools-mcp`
10- **Next.js < 16**: Requires `experimental.mcpServer: true` in next.config.js
11 
12Reference: https://nextjs.org/docs/app/guides/mcp
13 
14**Important**: Find the actual port of the running Next.js dev server (check terminal output or `package.json` scripts). Don't assume port 3000.
15 
16### Request Format
17 
18The endpoint uses JSON-RPC 2.0 over HTTP POST:
19 
20```bash
21curl -X POST http://localhost:<port>/_next/mcp \
22  -H "Content-Type: application/json" \
23  -H "Accept: application/json, text/event-stream" \
24  -d '{
25    "jsonrpc": "2.0",
26    "id": "1",
27    "method": "tools/call",
28    "params": {
29      "name": "<tool-name>",
30      "arguments": {}
31    }
32  }'
33```
34 
35### Available Tools
36 
37#### `get_errors`
38Get current errors from dev server (build errors, runtime errors with source-mapped stacks):
39```json
40{ "name": "get_errors", "arguments": {} }
41```
42 
43#### `get_routes`
44Discover all routes by scanning filesystem:
45```json
46{ "name": "get_routes", "arguments": {} }
47// Optional: { "name": "get_routes", "arguments": { "routerType": "app" } }
48```
49Returns: `{ "appRouter": ["/", "/api/users/[id]", ...], "pagesRouter": [...] }`
50 
51#### `get_project_metadata`
52Get project path and dev server URL:
53```json
54{ "name": "get_project_metadata", "arguments": {} }
55```
56Returns: `{ "projectPath": "/path/to/project", "devServerUrl": "http://localhost:3000" }`
57 
58#### `get_page_metadata`
59Get runtime metadata about current page render (requires active browser session):
60```json
61{ "name": "get_page_metadata", "arguments": {} }
62```
63Returns segment trie data showing layouts, boundaries, and page components.
64 
65#### `get_logs`
66Get path to Next.js development log file:
67```json
68{ "name": "get_logs", "arguments": {} }
69```
70Returns path to `<distDir>/logs/next-development.log`
71 
72#### `get_server_action_by_id`
73Locate a Server Action by ID:
74```json
75{ "name": "get_server_action_by_id", "arguments": { "actionId": "<action-id>" } }
76```
77 
78### Example: Get Errors
79 
80```bash
81curl -X POST http://localhost:<port>/_next/mcp \
82  -H "Content-Type: application/json" \
83  -H "Accept: application/json, text/event-stream" \
84  -d '{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"get_errors","arguments":{}}}'
85```
86 
87## Rebuild Specific Routes (Next.js 16+)
88 
89Use `--debug-build-paths` to rebuild only specific routes instead of the entire app:
90 
91```bash
92# Rebuild a specific route
93next build --debug-build-paths "/dashboard"
94 
95# Rebuild routes matching a glob
96next build --debug-build-paths "/api/*"
97 
98# Dynamic routes
99next build --debug-build-paths "/blog/[slug]"
100```
101 
102Use this to:
103- Quickly verify a build fix without full rebuild
104- Debug static generation issues for specific pages
105- Iterate faster on build errors
106