ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Use a Next.js MCP Server with VS Code

Connect Next.js 16+ to VS Code’s MCP tools, inspect live errors and routes, and troubleshoot configuration, security, and runtime issues.

By the ScreenshotNeo team1 October 20266 min read

Direct answer: For Next.js 16 or later, create a root .mcp.json containing the next-devtools-mcp server, open the project in VS Code, and run the development server. The package discovers the running Next.js instance so an MCP-capable agent can inspect live errors, routes, metadata, logs, Server Actions, and other development context.

1. Requirements

  • Next.js 16 or later.
  • The next-devtools-mcp package, invoked with npx.
  • VS Code with MCP support enabled in your environment.
  • A project-local development server, such as npm run dev.

The server is intended for development. It discovers a running Next.js application; it does not replace your production server or deployment configuration.

2. Add the portable MCP configuration

At the project root, create .mcp.json:

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

The root location matters. Put the file beside package.json, not inside app, pages, or .vscode. This is the portable MCP format documented for the Next.js development tools package.

Start the application

npm run dev

Use the equivalent command for your package manager:

pnpm dev
# or
yarn dev
# or
bun dev

If the development server was already running when you created .mcp.json, stop and restart it. This gives the MCP package a fresh opportunity to discover the instance.

3. Use VS Code’s workspace-specific format instead

VS Code also supports a file at .vscode/mcp.json. Its schema is different: the top-level key is servers, not mcpServers.

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

Choose one format deliberately. Use the root .mcp.json when you want a portable project configuration that compatible MCP clients can consume. Use .vscode/mcp.json when you want VS Code’s configuration assistance and management actions. Do not paste the portable object unchanged into the VS Code-specific file.

VS Code can also manage user-profile MCP servers. A user-profile server is available across workspaces; a workspace server travels with the project and is easier for a team to review and reproduce. In remote or Agent Host sessions, check where the configured command will run.

4. Connect and inspect the available tools

  1. Open the project folder in VS Code.
  2. Confirm the MCP configuration is in the intended location.
  3. Start or restart the Next.js development server.
  4. Open VS Code’s MCP server view or run its MCP management commands.
  5. Start the next-devtools server if it is not started automatically.
  6. Ask your MCP-capable agent a concrete question, such as What errors are currently in my application?

The Next.js guide describes access to current build, runtime, and type errors; development logs; page routes and component metadata; project metadata; Server Action lookup; a Next.js knowledge base; migration and upgrade helpers; cache-component guidance; and browser testing integration. These capabilities can evolve with the framework and package versions, so inspect the tools exposed by your installed version.

5. A repeatable setup checklist

Check Expected result
Framework version Next.js 16 or later
File location .mcp.json at the project root, or .vscode/mcp.json for VS Code format
Schema key mcpServers in portable format; servers in VS Code format
Command npx -y next-devtools-mcp@latest
Application state Development server is running and was restarted after configuration changes
VS Code state The server appears in the MCP view and exposes tools

6. Troubleshooting

The server does not appear

Cause: VS Code has not loaded the file, or the file is outside the opened workspace.

Fix: Open the directory containing the configuration as the workspace root. Check the MCP server view, reload the window, and verify the JSON parses correctly.

VS Code reports an invalid configuration

Cause: The two configuration formats were mixed.

Fix: For .mcp.json, use a top-level mcpServers object. For .vscode/mcp.json, use a top-level servers object and the VS Code server entry format.

The server starts but cannot find the app

Cause: The Next.js development server is not running, is running in another workspace, or was started before the MCP configuration was added.

Fix: Run npm run dev from the project root and restart an already-running process. Confirm that the opened VS Code folder is the same project whose development server is running.

The package fails to launch with npx

Cause: The local Node.js environment cannot resolve or execute the package.

Fix: Check that Node.js and npx are available, inspect the exact command in the MCP configuration, and review the MCP server output in VS Code. If your environment blocks package downloads, use the approved network or package-cache policy for that environment.

Tools are missing or changed

Cause: MCP capabilities are tied to the installed Next.js and next-devtools-mcp versions and can change as they evolve.

Fix: Inspect the server’s currently advertised tools, verify the framework version, and update the package only after reviewing the version change in your project workflow.

A remote session behaves differently

Cause: VS Code may run workspace or user-profile servers on a remote or Agent Host environment.

Fix: Check the MCP management UI for the execution location and ensure that Node.js, npx, the project files, and the running Next.js process are available in that same environment.

7. Security considerations

A local MCP server command can execute arbitrary code on your machine. Review the publisher, package name, arguments, and configuration before starting it. This setup invokes npx to run next-devtools-mcp; understand which package source your environment will use and what permissions the process has. Keep project secrets out of prompts and logs, and prefer workspace configuration that your team can inspect in version control.

8. Performance, reliability, and cost

  • Performance: Keep the development server running while you work so discovery and tool calls do not repeatedly pay startup overhead. Restart only after configuration or dependency changes.
  • Reliability: Pin or review package versions according to your team’s normal dependency policy. The @latest example follows the documented setup, but evolving tools may expose different capabilities over time.
  • Diagnostics: Use the MCP server view and server output when a call fails. Compare the reported tool list with the version of Next.js in the workspace.
  • Cost: The documented setup is local development configuration. Any cost depends on the AI client, model, hosting, or package policies you choose; the research does not establish a fee for the Next.js MCP package itself.

9. Capture the running app for documentation or review

Once an agent can inspect the live app, you may also need stable screenshots of routes, states, or rendered components. A browser automation stack can handle this, but it requires managing a browser, waits, cookies, popups, and failed pages yourself.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One request returns a PNG, JPEG, WebP, or PDF, and its MCP tools include take_screenshot, get_page_info, and capture_pdf.

Using the API is a single GET request. See the ScreenshotNeo API documentation for the complete option list.

cURL

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

Python

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

Node.js

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

Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing result. You can also use full-page capture, element selectors, device presets, custom waits, headers, cookies, JavaScript, CSS, blocking rules, PDFs, caching, signed links, async webhooks, bulk capture, and the MCP server for AI agents.

The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

10. FAQ

Does this work with Next.js versions before 16?

The documented prerequisite is Next.js 16 or later.

Should I commit the MCP configuration?

Commit a workspace configuration when the team should share it, after reviewing the command and package source. Keep personal servers in your user profile when they are not project dependencies.

Do I need both configuration files?

No. Choose the portable root file or the VS Code-specific file and use its matching schema.

Can the MCP server inspect production?

The documented workflow discovers a running Next.js development instance. Treat production inspection as a separate workflow unless your installed tools explicitly support it.

What should I ask the agent first?

Ask for current application errors, then request route, component, log, or Server Action details to narrow the diagnosis.

Keep reading