Ищешь "Next.js MCP server" — и находишь две разные задачи с одинаковым названием. Одним нужно, чтобы их coding-агент видел, что происходит внутри Next.js-приложения, которое они пишут: ошибки на странице, маршруты, проблемы сборки. Другим нужно превратить своё Next.js-приложение в MCP server, чтобы Claude или ChatGPT могли вызывать инструменты, которые предоставляет их сайт. Большинство найденных нами страниц описывают что-то одно и смешивают это с другим, а многие вдобавок показывают старую версию библиотеки для второй задачи.
Это руководство охватывает обе задачи. Мы прогнали каждую команду и каждый пример кода ниже 14 ноября 2026 года на Next.js 16.4.6, next-devtools-mcp 0.4.0, mcp-handler 2.4.0, @modelcontextprotocol/server 2.4.0 и zod 4.6.7, на macOS. Где результат расходился с документацией, мы об этом говорим.
Что вам нужно?
| Вы хотите | Используйте | Где работает | Что получает ИИ |
|---|---|---|---|
| Дать Claude Code, Cursor или Codex отлаживать приложение, которое вы пишете | Встроенный /_next/mcp плюс next-devtools-mcp |
Ваша машина, только при next dev |
Ошибки в реальном времени, маршруты, логи, проверки компиляции, документацию под вашу версию |
| Дать ИИ-приложениям инструменты из вашего продукта (поиск, заказы, документацию) | Свой маршрут на mcp-handler |
Там, где развёрнуто приложение | Только те инструменты, которые вы напишете |
| И то и другое | Оба, они не конфликтуют |
Если сомневаетесь, скорее всего вам нужен первый вариант. Это одна команда и никакого кода.
Часть 1: подключаем кодинг-агента к запущенному приложению Next.js
Что Next.js 16 отдаёт по пути /_next/mcp
Начиная с Next.js 16, next dev отвечает на MCP-запросы по пути /_next/mcp. Эта возможность включена по умолчанию. Мы отправили туда tools/list через curl и получили в ответ девять инструментов:
| Инструмент | Что возвращает | Что нужно |
|---|---|---|
get_errors |
Текущие ошибки: валидация next.config, ошибки рантайма в браузере, ошибки сборки с source-mapped стеками |
Страница, открытая в браузере, — для ошибок рантайма |
get_logs |
Путь к файлу лога dev-сервера с выводом консоли браузера и сервера | |
get_page_metadata |
Что повлияло на текущий рендер страницы | Страница, открытая в браузере |
get_project_metadata |
Путь к проекту и URL dev-сервера | |
get_routes |
Все маршруты, сгруппированные по appRouter и pagesRouter, динамические сегменты в виде [param] |
|
get_server_action_by_id |
Исходный файл и имя экспорта Server Action | |
get_compilation_issues |
Ошибки резолва, отсутствующие модули, ошибки трансформации по всем маршрутам | Turbopack |
compile_route |
Компилирует один маршрут, не запрашивая его | Turbopack |
get_request_insights |
Таймлайны последних запросов, fetches и поведение кеша | experimental.requestInsights |
Сервер представился как "Next.js MCP Server" версии 0.2.0. На нашем тестовом приложении из двух страниц get_routes вернул ровно то, что у нас было: / и /api/mcp.
Инструменты компиляции — тихая победа. Агент, который только что отредактировал три файла, может спросить у запущенного dev-сервера, компилируются ли они, вместо того чтобы запускать полный next build, пока код ещё наполовину готов.
Прежде чем на это полагаться, знайте о двух ограничениях. Это работает только в режиме разработки: мы собрали то же приложение и запустили next start, и /_next/mcp вернул 404. И нужен Next.js 16. На 15 по этому пути ничего нет; npx @next/codemod@latest upgrade latest — тот путь обновления, который предлагает сам инструментарий.
Чтобы отключить, установите experimental.mcpServer в false в next.config.
Устанавливаем next-devtools-mcp
Ваш агент не общается с /_next/mcp напрямую. Пакет next-devtools-mcp — это небольшой stdio-сервер, который находит запущенные dev-серверы и перенаправляет им вызовы. Начиная с версии 0.4.0 это тонкий коннектор с четырьмя инструментами:
nextjs_indexперечисляет запущенные dev-серверы Next.js и инструменты, которые каждый из них предоставляет.nextjs_callзапускает один из этих инструментов на сервере, если передать емуportиtoolName.nextjs_docsнаправляет агента к документации, которая поставляется внутри установленного Next.js, вnode_modules/next/dist/docs/, чтобы ответы соответствовали вашей версии.browser_evalнаправляет агента к CLIagent-browserдля проверки страниц в настоящем браузере.
Нужен Node.js 20.19 или новее. Выберите свой клиент:
Claude Code
claude mcp add next-devtools npx next-devtools-mcp@latest
Codex
codex mcp add next-devtools -- npx next-devtools-mcp@latest
На Windows 11 Codex также требует env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" } и startup_timeout_ms = 20_000 в .codex/config.toml, согласно README.
Gemini CLI
gemini mcp add next-devtools npx next-devtools-mcp@latest
Добавьте -s user, чтобы установить его для всех проектов, а не только для текущего.
VS Code с Copilot
code --add-mcp '{"name":"next-devtools","command":"npx","args":["-y","next-devtools-mcp@latest"]}'
Cursor или любой клиент, читающий JSON-файл
{
"mcpServers": {
"next-devtools": {
"command": "npx",
"args": ["-y", "next-devtools-mcp@latest"]
}
}
}
Положите его в .mcp.json в корне проекта, чтобы поделиться с командой через git, или в ~/.cursor/mcp.json, если нужен только Cursor.
Все агенты сразу
npx add-mcp next-devtools-mcp@latest
add-mcp записывает запись для каждого кодинг-агента, которого найдёт на машине.
Проверяем, что всё работает
Сначала запустите dev-сервер. Затем откройте страницу, над которой работаете, в браузере, потому что get_errors и get_page_metadata читают из живых сессий браузера. Теперь спросите у агента то, что знает только запущенное приложение:
- "Какие ошибки сейчас есть в приложении?"
- "Перечисли маршруты и скажи, какие из них динамические."
- "Компилируется ли
/blog/[slug]?"
В Claude Code вы увидите вызовы вроде nextjs_index, а затем nextjs_call с toolName: "get_errors". Если агент отвечает, читая ваши файлы, значит он не подключился.
Можно также проверить эндпоинт без всякого агента:
curl -s -X POST http://localhost:3000/_next/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
Список инструментов означает, что с Next.js всё в порядке, а проблема — между агентом и next-devtools-mcp.
С чем мы столкнулись: dev-серверы на других портах
Наше тестовое приложение работало на порту 3417, потому что порт 3000 был занят. nextjs_index его не нашёл. Зато нашёл другой проект, который случайно работал на 3000.
Чтение исходников пакета объяснило почему. На macOS и Linux next-devtools-mcp 0.4.0 сначала ищет процессы с именем ровно next-server. На нашем Mac процесс называется next-server (v16.4.6), поэтому совпадение не сработало, и пакет перешёл к перебору портов с 3000 по 3010. Dev-сервер на любом другом порту для него невидим.
Исправление простое. nextjs_call принимает порт напрямую, и на 3417 всё заработало, как только мы его передали:
{ "port": 3417, "toolName": "get_routes" }
Так что если у вас больше одного проекта или вы используете нестандартный порт, скажите агенту один раз: "dev-сервер на порту 3417". Он вызовет инструмент с этим портом. Держать проекты в диапазоне 3000–3010 тоже помогает избежать проблемы.
Часть 2: собираем свой MCP server внутри приложения на Next.js
Здесь речь о другом: ваше приложение на Next.js становится тем, к чему Claude, Cursor или ChatGPT могут подключиться по URL. Типичные инструменты — поиск по вашему контенту, запрос в вашу базу данных или действие вроде создания тикета в поддержку.
Протокольную часть берёт на себя mcp-handler от Vercel. Он превращает описание сервера в обычную функцию (Request) => Response — ровно то, что экспортирует Route Handler в Next.js.
Во второй версии многое изменилось
Большинство туториалов до сих пор показывают первую версию: с Redis, SSE-эндпоинтом и динамическим маршрутом [transport]. Вторая версия проще, и старые сниппеты на ней не работают:
| mcp-handler 1.x | mcp-handler 2.x | |
|---|---|---|
| Пакет SDK | @modelcontextprotocol/sdk 1.x |
@modelcontextprotocol/server 2.x |
| zod | 3 | 4.2 или новее |
| Node.js | 20 или новее | |
| Транспорты | Streamable HTTP и SSE | Только Streamable HTTP, без состояния |
| Redis | Нужен для SSE | Не используется |
| Опции маршрутизации | basePath, maxDuration, redisUrl и другие |
Убраны: монтируйте обработчик на нужный маршрут |
Если остаётесь на 1.x, держите @modelcontextprotocol/sdk версии 1.26.0 или новее. В README mcp-handler более ранние версии SDK отмечены из-за уязвимости в безопасности.
Установка
npm install mcp-handler@^2 @modelcontextprotocol/server@^2 zod@^4
Маршрут
Создайте app/api/mcp/route.ts. Этот обработчик даёт AI-клиентам поиск по постам блога. Замените массив на свою базу данных или CMS.
import { createMcpHandler } from "mcp-handler";
import { z } from "zod";
const posts = [
{ slug: "edge-caching", title: "Caching at the edge", body: "How we cache HTML at the edge for 10 minutes." },
{ slug: "image-sizes", title: "Picking image sizes", body: "Three widths cover most layouts." },
];
const handler = createMcpHandler(
(server) => {
server.registerTool(
"search_posts",
{
title: "Search posts",
description: "Find blog posts whose title or body contains the query.",
inputSchema: z.object({ query: z.string().min(2) }),
},
async ({ query }) => {
const q = query.toLowerCase();
const hits = posts.filter((p) => `${p.title} ${p.body}`.toLowerCase().includes(q));
return {
content: [{ type: "text", text: hits.length ? hits.map((p) => `${p.title} (/blog/${p.slug})`).join("\n") : "No posts found." }],
};
},
);
},
{ serverInfo: { name: "my-blog", version: "1.0.0" } },
);
export { handler as GET, handler as POST };
/api/mcp — всего лишь соглашение. Обработчик не смотрит на путь, так что app/mcp/route.ts подойдёт так же хорошо. Дайте клиентам полный URL того маршрута, который выберете.
Задайте serverInfo. Без него наш сервер представлялся клиентам как "mcp-typescript server on vercel" — именно это пользователи видят в списке серверов своего клиента.
Проверка через curl
При запущенном npm run dev эти три запроса — полный цикл. Мы прогнали их на маршруте выше:
curl -s -X POST http://localhost:3000/api/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
Ответ пришёл одним server-sent event с "serverInfo":{"name":"my-blog","version":"1.0.0"}. Замените тело на {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}, чтобы увидеть search_posts с его JSON Schema, а на это — чтобы запустить инструмент:
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_posts","arguments":{"query":"edge"}}}
Мы получили Caching at the edge (/blog/edge-caching). Обычный GET на этот маршрут вернул 405, и это ожидаемо: вторая версия не хранит состояние, и долгоживущего потока для открытия у неё нет.
Если вместо curl хочется посмотреть в интерфейсе, подойдёт MCP Inspector: npx @modelcontextprotocol/inspector, затем подключитесь к http://localhost:3000/api/mcp с транспортом Streamable HTTP.
Подключение клиента
Клиенты, которые умеют Streamable HTTP, подключаются по URL.
Claude Code
claude mcp add --transport http my-blog http://localhost:3000/api/mcp
Cursor (~/.cursor/mcp.json)
{
"mcpServers": {
"my-blog": { "url": "http://localhost:3000/api/mcp" }
}
}
VS Code (.vscode/mcp.json)
{
"servers": {
"my-blog": { "type": "http", "url": "http://localhost:3000/api/mcp" }
}
}
Claude Desktop читает удалённые серверы из Settings › Connectors. Для локального URL в claude_desktop_config.json пробросьте его через mcp-remote:
{
"mcpServers": {
"my-blog": { "command": "npx", "args": ["-y", "mcp-remote", "http://localhost:3000/api/mcp"] }
}
}
После деплоя замените localhost-URL на настоящий, например https://your-app.vercel.app/api/mcp. Наш конструктор конфигов сгенерирует такие сниппеты для 15 клиентов, если вы добавите туда свой сервер.
Защитите до деплоя
Задеплоенный маршрут публичен. Любой, кто найдёт URL, сможет вызывать ваши инструменты, поэтому добавьте авторизацию до первого деплоя, а не после.
withMcpAuth оборачивает обработчик. Вот версия, которую мы проверили, с одним общим токеном из переменной окружения:
import { createMcpHandler, withMcpAuth } from "mcp-handler";
// createMcpHandler(...) as above
const verifyToken = async (_req: Request, bearerToken?: string) => {
if (!bearerToken || bearerToken !== process.env.MCP_TOKEN) return undefined;
return { token: bearerToken, clientId: "team", scopes: ["posts:read"] };
};
const authed = withMcpAuth(handler, verifyToken, { required: true });
export { authed as GET, authed as POST };
required: true важен. Без него запрос без валидного токена всё равно проходит. С ним наш неаутентифицированный вызов получил:
HTTP/1.1 401 Unauthorized
www-authenticate: Bearer error="invalid_token", error_description="No authorization provided", resource_metadata="http://localhost:3417/.well-known/oauth-protected-resource"
а тот же вызов с Authorization: Bearer <token> — 200.
По этой ссылке resource_metadata клиенты с поддержкой OAuth находят вашу страницу входа. Отдайте её из app/.well-known/oauth-protected-resource/route.ts:
import { metadataCorsOptionsRequestHandler, protectedResourceHandler } from "mcp-handler";
const handler = protectedResourceHandler({ authServerUrls: ["https://auth.example.com"] });
const corsHandler = metadataCorsOptionsRequestHandler();
export { handler as GET, corsHandler as OPTIONS };
Он ответил {"resource":"http://localhost:3417","authorization_servers":["https://auth.example.com"]}. Укажите в authServerUrls своего настоящего провайдера идентификации. Для реальных пользователей замените общий токен проверкой токенов этого провайдера и проверяйте requiredScopes для каждого маршрута. Текущая ревизия спецификации, 2026-07-28, переносит регистрацию клиентов с Dynamic Client Registration на Client ID Metadata Documents; эта работа происходит в вашем сервере авторизации, а маршрут в Next.js не меняется.
Внутри инструмента проверенная идентичность лежит в ctx.http?.authInfo, так что инструмент может фильтровать результаты по аккаунту вызывающего.
Проблемы и решения
| Что видно | Причина | Решение |
|---|---|---|
[error] No server info found от next-devtools-mcp |
Не запущен dev-сервер Next.js 16 или он слушает порт вне диапазона 3000–3010 | Запустите npm run dev; если порт другой, передайте агенту этот порт для nextjs_call |
ERR_MODULE_NOT_FOUND для next-devtools-mcp/dist |
Устаревший кеш npx | Очистите кеш npx и перезапустите клиент |
404 на /_next/mcp |
Next.js 15 или старше, next start или experimental.mcpServer: false |
Обновите версию, используйте next dev или уберите флаг |
| Агент отвечает по файлам и ни разу не вызывает инструменты | Клиент не загрузил сервер | Перезапустите клиент и проверьте его список MCP; в Claude Code выполните /mcp |
405 на GET /api/mcp |
Нормально для mcp-handler 2 | Ничего исправлять не нужно; клиенты используют POST |
401 с заголовком WWW-Authenticate |
withMcpAuth с required: true и без токена |
Отправьте Authorization: Bearer ... или войдите через OAuth-поток клиента |
Код из старого руководства падает на redisUrl или basePath |
Написан для mcp-handler 1 | Уберите эти опции и смонтируйте маршрут там, где нужно |
| «The module was automatically converted to an EcmaScript module» на новом проекте | npm init добавил "type": "commonjs" в package.json |
Удалите поле type; Next.js сам разбирается с модулями |
Последний пункт стоил нам пяти минут на пустом тестовом проекте. В create-next-app такой проблемы нет.
Next.js MCP servers в нашем каталоге
На 14 ноября 2026 года в каталоге HostedMCP было 19 активных серверов с Next.js в названии, и 4 из них прошли наши правила индексации. Два, которые важны для этого руководства:
| Сервер | Звёзды | Оценка проверок | Что это |
|---|---|---|---|
| vercel/next-devtools-mcp | 836 | 89 | Коннектор из части 1 |
| vercel-labs/mcp-handler | 699 | 86 | Библиотека из части 2 |
Число звёзд взято из GitHub на момент последнего обновления; оценка проверок — это наш автоматический обзор репозитория, лицензии, поддержки, цепочки поставок и описаний инструментов, а доказательства приведены в отчёте о проверках каждого сервера. Большинство из остальных 17 — это стартовые шаблоны или узкоспециализированные инструменты с небольшим числом звёзд. Проверяйте их так же, прежде чем устанавливать.
Замечания по безопасности
Dev-эндпоинт предназначен только для разработки, но он не является приватным. Пока работает next dev, любой процесс, который может достучаться до порта, может прочитать путь к вашему проекту, маршруты и расположение логов. Не привязывайте dev-сервер к общему сетевому адресу, пока в его окружении хранятся секреты.
Ваш собственный маршрут становится публичным API с момента деплоя. Относитесь к каждому инструменту как к эндпоинту: проверяйте входные данные по схеме, возвращайте только то, что вызывающая сторона может видеть, и никогда не помещайте секреты или внутренние URL в описания инструментов, потому что эти описания читает модель, а также любой, кто получает список ваших инструментов. В нашем руководстве по безопасности MCP риски разобраны по порядку.
Куда двигаться дальше
Если нужны детали протокола, лежащие в основе этого пути, в разделе как собрать MCP server показано, как собрать его на чистом TypeScript и Python. Когда ваш сервер заработает, отправьте репозиторий — HostedMCP добавит его в каталог со сниппетами установки для каждого клиента и запустит свои проверки.