How do we give AI coding assistants real-time access to the internal state of our running applications? Introducing next-devtools-mcp, Vercel's innovative solution that bridges the gap between AI assistants like Claude, Cursor, and Copilot and the Next.js development environment through the Model Context Protocol.
vercel
Organization
next-devtools-mcp
Next.js Development for Coding AgentReleased in October 2025, this open-source MCP server represents a step torward improving how developers interact with their Next.js applications. Rather than relying on guesswork or outdated documentation, AI assistants can now query live runtime diagnostics, access official documentation on demand, automate upgrades, and even control browsers for testing, all through a standardized protocol.
What next-devtools-mcp Offers
At its core, next-devtools-mcp provides six powerful tools that transform how AI assistants interact with Next.js applications.
- The nextjs_runtime tool connects to your development server's MCP endpoint, exposing real-time build errors, runtime logs, route metadata, and Server Action details.
- The nextjs_docs tool searches and fetches official Next.js documentation on demand, ensuring AI assistants always reference current information.
- For automation, upgrade_nextjs_16 guides migrations to Next.js 16 through official codemods,
- while enable_cache_components automates the transition to Cache Components mode with intelligent error detection and fixes
- The browser_eval tool integrates Playwright for visual testing and browser automation
- and the init tool establishes proper context at session start, documenting all available capabilities.
Beyond the tools, the system includes a curated knowledge base with 12 specialized resources covering Cache Components mechanics, migration strategies, and Next.js 16 fundamentals. Each resource uses URI-based addressing for on-demand loading, preventing context window overflow.
The architecture supports multiple AI coding assistants including Claude, Cursor, Copilot, Gemini, and Warp, with both CLI-based and manual configuration options. Privacy is built-in through optional telemetry that respects the NEXT_TELEMETRY_DISABLED environment variable, with all data stored locally.
The Challenge of AI-Assisted Framework Development
Modern web frameworks like Next.js have grown increasingly sophisticated, with complex caching strategies, server-side rendering nuances, and rapidly evolving APIs. When developers work with AI coding assistants, these tools traditionally rely on training data that may be months old or lack access to the actual state of a running application. This creates a fundamental disconnect such that an AI assistant might suggest outdated patterns, miss runtime errors, or provide guidance based on different framework versions.
The challenges multiply when attempting major version upgrades. Next.js 16 introduced significant changes including Cache Components, asynchronous request APIs, and new rendering behaviors.
Developers found themselves in a difficult position, needing to upgrade their applications while navigating breaking changes, but without giving their AI assistants the context they needed to provide accurate guidance.
The documentation exists, but how does an AI assistant know which specific documentation to reference at the right moment? How can it detect and fix migration-specific errors without seeing the actual application state?
A Three-Pillar Architecture for AI-Powered Development
Vercel's solution is elegantly comprehensive, built on three fundamental capabilities that work in concert. First and foremost is runtime diagnostics through Next.js 16's built-in MCP endpoint.
When you start your development server with nextjs_runtime, the server automatically discovers your running Next.js application and connects to its `/_next/mcp` endpoint. This gives AI assistants unprecedented access to real-time build errors, type errors, application routes, development logs, and even Server Action metadata. It's like giving your AI assistant x-ray vision into your running application.
The second pillar is development automation. The upgrade_nextjs_16 tool guides AI assistants through executing official Next.js codemods, while enable_cache_components handles the intricate process of migrating to Cache Components mode, including automated error detection and fixes.
Meanwhile, the browser_eval tool integrates with Playwright for visual verification and end-to-end testing, allowing AI assistants to actually see and interact with your application in a browser.
The third pillar is intelligent documentation access. Rather than hoping an AI assistant's training data is current, the nextjs_docs tool provides a two-step process: search official Next.js documentation by keyword to find relevant paths, then fetch the complete markdown content.
This is complemented by a curated knowledge base split into 12 focused sections on Cache Components, migration guides for Next.js 16, and fundamental concepts like client-side rendering boundaries. Each resource is loaded on-demand, providing targeted knowledge without overwhelming the AI's context window.
Why This Architecture Stands Out
What makes next-devtools-mcp particularly impressive is its thoughtful implementation of the Model Context Protocol. MCP, an open-source standard from Anthropic, acts like a USB-C port for AI applications providing a standardized way to connect AI assistants to external systems.
The elegance lies in how Vercel has implemented this bidirectionally: next-devtools-mcp acts as both an MCP server (exposing tools to AI assistants) and an MCP client (connecting to other servers like the Next.js runtime and Playwright).
The initialization workflow demonstrates exceptional user experience design. The init tool establishes proper context at the start of every session, documenting all available tools and establishing a documentation-first approach.
Developers can even configure their AI assistants to call this tool automatically, ensuring consistent behavior across projects. This attention to the developer workflow shows a deep understanding of how humans and AI work together in practice.
Key Capabilities That Transform Development
The runtime diagnostics capability fundamentally changes how developers debug Next.js applications with AI assistance. When an AI assistant executes `nextjs_runtime` with the `get_errors` tool, it receives structured information about build errors, runtime exceptions, and type checking issues, the same information you would see in your terminal, but now accessible programmatically.
The `get_logs` tool provides the path to development logs capturing both browser console output and server logs. The `get_page_metadata` tool reveals your complete routing structure, component hierarchies, and metadata, while `get_project_metadata` exposes configuration details and the dev server URL. This is complemented by `get_server_action_by_id`, which allows AI assistants to trace Server Actions back to their source files, an invaluable feature when debugging form submissions or API calls.
The browser automation integration showcases how different MCP servers can compose together. When you use `browser_eval`, next-devtools-mcp automatically installs and manages a connection to @playwright/mcp, giving AI assistants the ability to navigate pages, click elements, fill forms, take screenshots, execute JavaScript in the browser context, and capture console messages. This is particularly powerful during Next.js upgrades when you want to visually verify that pages render correctly and catch hydration errors or client-side issues that might not appear in server logs.
The documentation integration is more sophisticated than it initially appears. Rather than embedding documentation directly, next-devtools-mcp uses Next.js's official documentation search API. This ensures AI assistants always reference the most current documentation, with the ability to filter by router type (App Router, Pages Router, or both) and jump to specific sections using anchors.
The curated knowledge base resources use URI-based addressing (like `cache-components://core-mechanics`), allowing AI assistants to request specific sections without loading unnecessary content. Each of the 12 Cache Components resources focuses on a distinct aspect from public versus private caches to runtime prefetching patterns to common error scenarios.
Technical Architecture and Implementation
The codebase is built with TypeScript targeting ES2022 and using native ES modules throughout. The main entry point leverages the `@modelcontextprotocol/sdk` to create a Server instance with stdio transport, the standard communication method for MCP servers.
Tools, prompts, and resources are explicitly imported and registered, with each tool exposing an input schema (using Zod for validation), metadata, and an async handler function. The server converts these Zod schemas to JSON Schema for the MCP protocol, providing type-safe validation of arguments.
The internal architecture reveals careful attention to lifecycle management. The browser-eval-manager handles spawning and communicating with the Playwright MCP server as a child process, while the nextjs-runtime-manager implements server discovery by scanning common ports (3000, 3001, etc.) and verifying MCP endpoint availability. The mcp-client module provides a reusable client implementation for connecting to external MCP servers via stdio transport, demonstrating how MCP enables server composition.
Telemetry is implemented with privacy in mind. The system tracks tool invocations through an in-memory event queue that aggregates usage during the session. When the server shuts down, it spawns a detached background process that sends anonymized telemetry to Vercel's API. The implementation respects the `NEXT_TELEMETRY_DISABLED` environment variable, and all data is stored locally in `~/.next-devtools-mcp/`. The logger provides synchronous file logging for debugging, separate from the async telemetry pipeline.
The resource system demonstrates elegant modularity. Each resource exports metadata (URI, name, description, MIME type) and a handler function that returns content. During the build process, markdown files are copied from `src/resources/` to `dist/resources/` by copy-resources.js, allowing resources to read files from the build output. This separation of code and content makes the knowledge base maintainable where documentation updates don't require code changes, and resources can be added by simply creating new markdown files and minimal TypeScript metadata.
// Example: How tools are structured
export const inputSchema = {
action: z.enum(['discover_servers', 'list_tools', 'call_tool']).describe('Action to perform'),
port: z.number().optional().describe('Dev server port (auto-discovers if not provided)'),
toolName: z.string().optional().describe('Name of the Next.js tool to invoke'),
args: z.record(z.unknown()).optional().describe('Arguments for the tool'),
};
export const metadata = {
name: 'nextjs_runtime',
description: 'Connect to Next.js dev server MCP endpoint for runtime diagnostics',
};
export async function handler(args: { action: string; port?: number; toolName?: string; args?: Record }): Promise {
// Implementation that connects to Next.js runtime and executes the requested action
// Returns JSON-formatted results
}
Real-World Applications and Developer Workflows
One of the most compelling use cases is migrating large Next.js codebases to version 16. A developer can start by asking their AI assistant to run the `init` tool to establish context, then execute `upgrade_nextjs_16` which guides them through updating package versions and running official codemods.
As the upgrade progresses, the AI assistant can query `nextjs_runtime` to see build errors in real-time, consult `nextjs_docs` to understand new APIs, and use `browser_eval` to visually verify that pages still render correctly. This transforms what could be days of manual work into a guided, iterative process with an AI pair programmer that has full visibility into the application state.
The Cache Components migration showcases the system's sophistication. When a developer enables Cache Components mode via `enable_cache_components`, the tool doesn't just update the configuration file; it actively monitors the dev server for specific error patterns like "Route ... used request.cookies without calling cacheLife or cacheTag" or "Dynamic data access requires cacheLife or cacheTag."
When these errors are detected, the tool automatically generates fixes and applies them, then verifies the errors are resolved. This level of automation would be impossible without runtime diagnostics and documentation access working together.
Enterprise teams are using next-devtools-mcp to standardize their Next.js development practices. By encoding best practices into the MCP resources and prompts, organizations ensure that every developer, and every AI assistant, follows consistent patterns.
The `nextjs_docs` tool becomes a living style guide, always referencing official documentation rather than relying on potentially outdated AI training data. Teams report faster onboarding as new developers leverage AI assistants that automatically reference the correct documentation for their Next.js version and project configuration.
Adoption and Ecosystem Growth
Since its release in October 2025, next-devtools-mcp has gained 361 stars and 19 forks on GitHub, demonstrating strong community interest as of November 12. The repository shows active maintenance with recent commits and quick responses to issues. The community has reported interesting edge cases, like issue #86 requesting HTTPS support for development servers wrapped in custom servers, showing that developers are pushing the boundaries of what's possible with the tool.
The project supports a remarkable range of AI coding assistants including Claude Code, Cursor, Amp, Codex, Gemini, VS Code Copilot, and Warp. Each has its own configuration instructions, reflecting Vercel's commitment to broad ecosystem compatibility. T
The documentation provides both CLI-based installation (`code --add-mcp`) and manual configuration steps, ensuring developers can integrate the MCP server regardless of their tooling preferences. This wide compatibility has accelerated adoption across different development environments.
Vercel has provided extensive resources to support the community. The CLAUDE.md file offers detailed guidance for AI assistants working with the codebase, documenting architecture, build processes, and common development patterns.
The README includes not just usage instructions but also pro tips like auto-initializing the init tool at the start of every session. This level of documentation quality reflects a mature open-source project designed for long-term community growth.
Open Source Under the MIT License
The project is released under the MIT License, one of the most permissive open-source licenses available. This means developers and organizations can freely use, modify, and distribute the software for commercial or non-commercial purposes without requiring explicit permission from Vercel. The only requirement is including the original copyright notice and license text in any substantial portions of the software.
The MIT License provides important freedoms while limiting liability. Vercel provides the software "as is" without warranty of any kind, meaning users assume responsibility for any issues that arise from its use. This licensing choice aligns with Vercel's broader open-source strategy—they've open-sourced Next.js itself, along with tools like Turbo and v0, fostering a collaborative ecosystem while maintaining commercial offerings around deployment and infrastructure.
About Vercel: Building the Frontend Cloud
Vercel is the company behind Next.js, the React framework that powers websites for companies like Nike, Uber, TikTok, and Notion. Founded with the mission to make the web faster and more personalized, Vercel provides what they call the "Frontend Cloud", infrastructure and developer experience tools for building, scaling, and securing modern web applications. The company has raised funding from top-tier investors including Accel, Bedrock, GV (Google Ventures), and notable individual investors like Jordan Walke (creator of React) and Brendan Eich (creator of JavaScript and founder of Brave).
Vercel's product philosophy centers on making deployment "as easy as a single tap" while ensuring sites are fast from everywhere and accessible to everyone. Their platform handles the complexity of global edge deployment, serverless functions, and incremental static regeneration, allowing developers to focus on building features rather than managing infrastructure. The company's open-source contributions extend beyond Next.js to include Turborepo (for monorepo management), SWC (a Rust-based JavaScript compiler), and numerous developer tools and integrations.
The release of next-devtools-mcp reflects Vercel's forward-thinking approach to AI-assisted development. Rather than treating AI coding assistants as competitors to their platform, Vercel is actively building tools that enhance AI capabilities within their ecosystem. This positions them uniquely at the intersection of web development frameworks, deployment infrastructure, and AI-powered developer tooling. Their recent launch of v0, an AI-powered interface design tool, further demonstrates this strategic focus on AI-enhanced development workflows.
Shaping the Future of AI-Assisted Framework Development
The implications of next-devtools-mcp extend far beyond Next.js. By implementing the Model Context Protocol, Vercel is pioneering what AI-assisted framework development could look like across the entire web ecosystem.
Imagine similar MCP servers for Vue.js, Angular, SvelteKit, or Remix; each providing runtime diagnostics, documentation access, best practices and automation tools tailored to their framework's specifics. The standardization that MCP provides means AI assistants could work seamlessly across different frameworks, adapting their behavior based on which MCP servers are available.
This project also challenges the notion of what development tools should look like in an AI-first world. Rather than building visual interfaces or CLI commands, next-devtools-mcp provides capabilities that AI assistants can orchestrate on behalf of developers. The human developer remains in control providing intent and making decisions while the AI handles the mechanical work of querying runtime state, searching documentation, and executing automations. This division of labor represents a mature vision of human-AI collaboration in software development.
From a business perspective, Vercel is positioning itself as essential infrastructure for the AI era. As more developers adopt AI coding assistants, frameworks and platforms that provide deep integration through protocols like MCP will have a significant advantage. next-devtools-mcp is a strategic play to ensure that Next.js and Vercel remain at the center of modern web development as AI assistants become ubiquitous. The early adoption and community enthusiasm suggest this strategy is resonating with developers.
A Blueprint for Framework Integration in the AI Era
next-devtools-mcp represents a significant milestone in the evolution of AI-assisted development. By giving AI assistants direct access to runtime diagnostics, official documentation, and automation capabilities through the Model Context Protocol, Vercel has created a blueprint that other framework authors will likely follow.
The project's thoughtful architecture balancing powerful capabilities with privacy considerations, supporting multiple AI assistants, and maintaining excellent documentation—demonstrates a mature approach to open-source AI tooling.
For Next.js developers, this tool immediately becomes valuable. The ability to ask an AI assistant to check your application for errors, search official documentation, or guide you through major version upgrades transforms the development experience.
For the broader development community, next-devtools-mcp offers insights into how frameworks can expose their internal state and capabilities to AI systems in standardized ways. As the Model Context Protocol gains adoption, we'll likely see an explosion of similar tools across different domains.
Whether you're building with Next.js, developing your own framework, or simply interested in how AI will change software development, next-devtools-mcp is worth exploring. Clone the repository, review the architecture, and experiment with the tools. The future of development is collaborative—humans and AI working together with shared access to the tools and information needed to build great software. Vercel has shown us what that future might look like, and it's compelling.
Bridging AI Assistants and Next.js: Exploring Vercel's next-devtools-mcp