Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
To connect Next.js development tools to VS Code, use Next.js 16 or later, add the next-devtools-mcp package to a project-level MCP configuration, and run the app’s development server. The portable setup is a root .mcp.json with an mcpServers key. VS Code’s own .vscode/mcp.json uses a different top-level key, servers, so the two files are not interchangeable without changing the schema.
What you need before connecting the server
- Next.js 16 or later. The documented Next.js MCP integration requires this framework version or newer.
- A project opened as a workspace in VS Code. Put the configuration at the project root if you want it to travel with the codebase.
- The
next-devtools-mcppackage. The recommended configuration invokes it throughnpx. - A running development server. Start it with
npm run devor the equivalent command for your package manager. The MCP package discovers the running Next.js instance rather than replacing your normal dev command.
If your development server was already running when you add the MCP configuration, stop and restart it. Discovery happens when the integration connects to the live development instance.
Choose the configuration file deliberately
There are two workspace-level formats. Select one instead of placing both in the project by accident.
| File | Top-level key | Best use | Trade-off |
|---|---|---|---|
.mcp.json at the project root |
mcpServers |
Portable configuration that can be used by compatible MCP clients | Uses the generic MCP schema rather than VS Code’s configuration assistance |
.vscode/mcp.json |
servers |
VS Code-specific management, configuration assistance, and server controls | Designed for VS Code rather than broad portability |
VS Code can also keep MCP servers in a user profile so they are available in multiple workspaces. A project-level file is usually easier for a team to review and reproduce. In remote or Agent Host sessions, check where VS Code is actually running the server; a local configuration may execute on a different machine than the editor window.
#1 Best Overall
Set up the portable root .mcp.json
- Open the Next.js project folder in VS Code. The folder containing
package.jsonshould be the workspace root. - Create a file named
.mcp.jsonin that folder. - Paste this configuration exactly:
{
"mcpServers": {
"next-devtools": {
"command": "npx",
"args": ["-y", "next-devtools-mcp@latest"]
}
}
}- Save the file, then start the development server in the integrated terminal:
npm run devUse pnpm dev, yarn dev, or bun dev when that is the command defined by your project. The MCP process is separate from the Next.js process; the package looks for the running development instance and connects to it.
- If the server was running before the file was created, restart it. Then reload or reopen the VS Code workspace if the MCP view does not immediately show the server.
Use VS Code’s .vscode/mcp.json format instead
VS Code’s workspace-specific file lives in the .vscode directory and uses servers, not mcpServers. Adapt the same command like this:
{
"servers": {
"next-devtools": {
"type": "stdio",
"command": "npx",
"args": ["-y", "next-devtools-mcp@latest"]
}
}
}Do not copy the portable example into .vscode/mcp.json unchanged. The different top-level key is the important distinction. VS Code provides actions to inspect and manage servers configured in this file, including starting, stopping, restarting, and viewing available tools.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →If you are working in a repository where other MCP-capable clients also need the server, the root .mcp.json is the more portable choice. If the setup is only for VS Code users and you want its configuration UI, use .vscode/mcp.json.
Start and verify the connection
1. Confirm the framework version
npm list nextCheck that the installed version is 16 or newer. If the command reports an older release, upgrade Next.js before troubleshooting MCP discovery.
2. Start the app in development mode
npm run devKeep this process running. The integration is intended to inspect a live development application, not a static export.
3. Inspect the MCP server in VS Code
Open VS Code’s MCP management commands or the MCP server view. Locate next-devtools, then inspect its status and exposed tools. If it is stopped, start or restart it from that view.
4. Ask a question that requires live project context
A useful first request is: “What errors are currently in my application?” A connected server can inspect the current development state instead of relying only on files pasted into a chat.
5. Check the result against the running app
Make a small code change, refresh the development server, and ask for the current errors or route metadata again. This confirms that the server is attached to the active instance rather than an old process.
What the Next.js MCP server can expose
The Next.js guide describes a set of development and knowledge tools. The exact list can evolve with the framework and the next-devtools-mcp package, so treat the tools visible in your VS Code MCP view as authoritative for your installed versions.
- Runtime and build diagnostics: inspect current build errors, runtime errors, and development logs.
- Type information: examine type errors reported by the active project.
- Route and component metadata: discover pages, routes, and relevant component information.
- Project metadata: give an agent context about the application structure and configuration.
- Server Action lookup: locate Server Actions while investigating how a request flows through the app.
- Next.js knowledge: consult framework guidance from the package’s knowledge base.
- Migration and upgrade help: get assistance when moving between framework versions.
- Cache Components guidance: investigate caching-related behavior and configuration.
- Browser testing integration: combine project context with browser-oriented checks when the exposed tool set supports it.
These capabilities do not turn VS Code into a production monitoring system. They are most useful while the application is running locally or in the development environment that the package can discover.
Recommended Free Tools
Security and team controls
Review the command before starting it
VS Code warns that local MCP servers can execute arbitrary code on the machine. This setup invokes npx, which downloads or runs a package command. Review the publisher, package name, arguments, and repository configuration before approving it.
Keep secrets out of prompts and configuration
Do not paste API keys, session cookies, production credentials, or private customer data into an agent conversation merely to diagnose a local error. Use the least-privileged environment possible and inspect what files or logs an agent is being asked to read.
Decide where remote sessions execute
With a remote workspace or Agent Host, the command may run on the remote host rather than your laptop. Verify that the Next.js process and MCP process are on the same reachable environment, and apply that host’s package and network policies.
Review repository changes
Keep the MCP file under version control when it is a team standard. If it is only a personal experiment, use the user-profile configuration or document why the workspace file should not be committed.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteTroubleshoot a server that does not connect
| Symptom | Likely cause | Fix |
|---|---|---|
No next-devtools server appears |
The file is in the wrong directory or VS Code has not loaded it | Put .mcp.json beside package.json, or put the VS Code file at .vscode/mcp.json. Reload the workspace and inspect the MCP server view. |
| Configuration error mentions the server key | The schema was mixed between formats | Use mcpServers only in root .mcp.json; use servers in .vscode/mcp.json. Check commas and quotation marks in the JSON. |
| The server starts but finds no application | The Next.js development process is not running, or it started before MCP was configured | Run npm run dev in the project root. Stop and restart an already-running development server after saving the MCP file. |
| The package cannot be invoked | npx is unavailable, blocked, or unable to reach the package registry |
Verify that Node.js and your package manager work in the same environment as VS Code. Check corporate proxy or registry policy, then retry the server from the MCP view. |
| Tools are visible but return stale information | The server is attached to an old process or a different workspace | Confirm the terminal’s current directory, restart the Next.js dev server, then restart the MCP server and repeat the request. |
| Local works but remote does not | The editor, MCP process, and Next.js process are on different hosts | Inspect the remote/Agent Host execution location and run both processes where they can discover the same development instance. |
| An agent proposes an unsafe action | MCP tools can expose powerful local context and commands | Stop the request, review the server package and prompt, and approve only actions you understand. Remove the server if the publisher or command is not trusted. |
Performance, reliability, and maintenance considerations
- Startup: invoking with
npx -ymay need to resolve the package before the first connection. A later connection can be faster if the package is already available in the environment. - Availability: the tools depend on the Next.js development server. Stopping, rebuilding, or moving that process can temporarily make runtime information unavailable.
- Version drift: the
@latesttag follows the package’s current release. Review changes when reproducibility matters, and test the configuration after upgrading Next.js or VS Code. - Resource use: logs, type analysis, and browser checks can consume CPU and memory in a large project. Ask for a focused route, error, or time range instead of requesting an unrestricted dump.
- Cost: this local setup does not add a hosted MCP service charge. You still pay any normal infrastructure, CI, or remote-development costs associated with the environment where it runs.
Or skip the browser setup
If your immediate goal is a clean image or PDF of a deployed page rather than interactive diagnosis, ScreenshotNeo provides a single HTTP request. It accepts cookie and consent banners like a visitor, removes more than 60 known consent platforms plus newsletter popups and chat widgets before capture, and reports whether a response was clean or billed. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed.
For a deployed Next.js URL, the cURL request is:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://your-next-app.example -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://your-next-app.example"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://your-next-app.example' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);See the ScreenshotNeo API documentation for parameters such as full-page capture, CSS selectors, device presets, dark mode, custom JavaScript, waits, blocking rules, PDFs, signed links, asynchronous jobs, and bulk capture. Its MCP server also lets Claude, Cursor, and other MCP clients call take_screenshot, get_page_info, and capture_pdf. The Free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account to get started.
Frequently asked questions
Can I connect this to a production deployment?
The documented package discovers a running Next.js development instance. Use it with the development server and keep production diagnostics in the monitoring systems designed for your deployment.
Should a team commit .mcp.json?
Commit it when every contributor should receive the same portable setup and your security review approves the command. For an individual experiment, keep it in a user profile or exclude it from the repository.
Why does VS Code use a different key?
.mcp.json follows the portable MCP format, while .vscode/mcp.json is VS Code’s own workspace schema. The portable file uses mcpServers; the VS Code file uses servers.
What should I ask first after connecting?
Ask for the errors currently in the application, then follow up with the affected route or component. This gives the agent a bounded request tied to live development context.
Frequently Asked Questions
Can I connect this to a production deployment?
The documented package discovers a running Next.js development instance. Use it with the development server and keep production diagnostics in the monitoring systems designed for your deployment.
Should a team commit .mcp.json?
Commit it when every contributor should receive the same portable setup and your security review approves the command. For an individual experiment, keep it in a user profile or exclude it from the repository.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Why does VS Code use a different key?
The portable .mcp.json format uses mcpServers, while VS Code’s .vscode/mcp.json schema uses servers.
What should I ask first after connecting?
Ask for the errors currently in the application, then follow up with the affected route or component so the request stays tied to live development context.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
