Cherchez « Next.js MCP server » et vous tombez sur deux tâches différentes qui portent le même nom. Certains veulent que leur agent de codage voie l'intérieur de l'application Next.js qu'ils développent : les erreurs sur la page, les routes, les problèmes de build. D'autres veulent transformer leur application Next.js en MCP server, pour que Claude ou ChatGPT puissent appeler les outils fournis par leur site. La plupart des pages que nous avons lues traitent l'une et brouillent l'autre, et beaucoup montrent encore l'ancienne version de la bibliothèque pour la seconde tâche.
Ce guide couvre les deux. Nous avons exécuté chaque commande et chaque exemple de code ci-dessous le 14 novembre 2026, sur Next.js 16.4.6, next-devtools-mcp 0.4.0, mcp-handler 2.4.0, @modelcontextprotocol/server 2.4.0 et zod 4.6.7, sous macOS. Lorsque le résultat différait de la documentation, nous le signalons.
Lequel vous faut-il ?
| Vous voulez | Utilisez | S'exécute | L'IA obtient |
|---|---|---|---|
| Permettre à Claude Code, Cursor ou Codex de déboguer l'application que vous écrivez | Le /_next/mcp intégré, plus next-devtools-mcp |
Sur votre machine, uniquement avec next dev |
Les erreurs en direct, les routes, les logs, les vérifications de compilation, une documentation alignée sur votre version |
| Fournir à des applications IA des outils issus de votre produit (recherche, commandes, docs) | Votre propre route avec mcp-handler |
Là où l'application est déployée | Les outils que vous écrivez, rien d'autre |
| Les deux | Les deux, ils n'entrent pas en conflit |
Si vous hésitez, c'est probablement la première option qu'il vous faut. Une seule commande suffit, sans code.
Partie 1 : connecter votre agent de codage à une application Next.js en cours d'exécution
Ce que Next.js 16 expose sur /_next/mcp
Depuis Next.js 16, next dev répond aux requêtes MCP sur /_next/mcp. C'est activé par défaut. Nous avons envoyé tools/list avec curl et obtenu neuf outils en retour :
| Outil | Ce qu'il renvoie | Nécessite |
|---|---|---|
get_errors |
Erreurs actuelles : validation de next.config, erreurs d'exécution dans le navigateur, erreurs de build avec piles source-mappées |
La page ouverte dans un navigateur pour les erreurs d'exécution |
get_logs |
Chemin du fichier de log de dev avec la console du navigateur et la sortie serveur | |
get_page_metadata |
Ce qui a contribué au rendu de la page actuelle | La page ouverte dans un navigateur |
get_project_metadata |
Chemin du projet et URL du serveur de dev | |
get_routes |
Toutes les routes regroupées par appRouter et pagesRouter, segments dynamiques sous la forme [param] |
|
get_server_action_by_id |
Fichier source et nom d'export d'une Server Action | |
get_compilation_issues |
Erreurs de résolution, modules manquants, erreurs de transformation sur toutes les routes | Turbopack |
compile_route |
Compile une route sans la requêter | Turbopack |
get_request_insights |
Chronologies des requêtes récentes, fetches et comportement du cache | experimental.requestInsights |
Le serveur s'annonçait comme « Next.js MCP Server » version 0.2.0. Sur notre application de test à deux pages, get_routes renvoyait exactement ce que nous avions : / et /api/mcp.
Les outils de compilation sont le gain discret. Un agent qui vient de modifier trois fichiers peut demander au serveur de dev en cours d'exécution s'ils compilent, au lieu de lancer un next build complet alors que le code est à moitié fait.
Deux limites à connaître avant de vous y fier. Il n'existe qu'en développement : nous avons buildé la même application et lancé next start, et /_next/mcp renvoyait 404. Et il faut Next.js 16. Sur la 15, il n'y a rien à ce chemin ; npx @next/codemod@latest upgrade latest est la voie de mise à niveau que l'outillage lui-même suggère.
Pour le désactiver, passez experimental.mcpServer à false dans next.config.
Installer next-devtools-mcp
Votre agent ne parle pas directement à /_next/mcp. Le paquet next-devtools-mcp est un petit serveur stdio qui trouve les serveurs de dev en cours d'exécution et leur transmet les appels. Depuis la version 0.4.0, c'est un connecteur léger avec quatre outils :
nextjs_indexliste les serveurs de dev Next.js en cours d'exécution et les outils que chacun expose.nextjs_callexécute l'un de ces outils sur un serveur, à partir de sonportet de sontoolName.nextjs_docsoriente l'agent vers la documentation embarquée dans votre installation de Next.js, dansnode_modules/next/dist/docs/, pour que les réponses correspondent à votre version.browser_evaloriente l'agent vers le CLIagent-browserpour vérifier les pages dans un vrai navigateur.
Il nécessite Node.js 20.19 ou plus récent. Choisissez votre client :
Claude Code
claude mcp add next-devtools npx next-devtools-mcp@latest
Codex
codex mcp add next-devtools -- npx next-devtools-mcp@latest
Sur Windows 11, Codex a aussi besoin de env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" } et de startup_timeout_ms = 20_000 dans .codex/config.toml, d'après le README.
Gemini CLI
gemini mcp add next-devtools npx next-devtools-mcp@latest
Ajoutez -s user pour l'installer pour tous les projets au lieu du projet courant.
VS Code avec Copilot
code --add-mcp '{"name":"next-devtools","command":"npx","args":["-y","next-devtools-mcp@latest"]}'
Cursor, ou tout client qui lit un fichier JSON
{
"mcpServers": {
"next-devtools": {
"command": "npx",
"args": ["-y", "next-devtools-mcp@latest"]
}
}
}
Placez-le dans .mcp.json à la racine du projet pour le partager avec l'équipe via git, ou dans ~/.cursor/mcp.json pour Cursor seul.
Tous les agents d'un coup
npx add-mcp next-devtools-mcp@latest
add-mcp écrit l'entrée pour chaque agent de codage qu'il trouve sur la machine.
Vérifier que ça fonctionne
Démarrez d'abord le serveur de dev. Ouvrez ensuite dans le navigateur la page sur laquelle vous travaillez, car get_errors et get_page_metadata lisent les sessions de navigateur actives. Demandez maintenant à l'agent quelque chose que seule l'application en cours d'exécution connaît :
- « Quelles erreurs l'application a-t-elle en ce moment ? »
- « Liste les routes et dis-moi lesquelles sont dynamiques. »
- « Est-ce que
/blog/[slug]compile ? »
Dans Claude Code, vous verrez des appels comme nextjs_index puis nextjs_call avec toolName: "get_errors". Si l'agent répond en lisant vos fichiers, il n'est pas connecté.
Vous pouvez aussi vérifier le point de terminaison sans aucun agent :
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":{}}'
Une liste d'outils signifie que Next.js va bien et que tout problème se situe entre l'agent et next-devtools-mcp.
Ce que nous avons rencontré : les serveurs de dev sur d'autres ports
Notre application de test tournait sur le port 3417, car le port 3000 était pris. nextjs_index ne l'a pas trouvée. Il a trouvé un autre projet qui se trouvait tourner sur 3000.
La lecture du code source du paquet a expliqué pourquoi. Sur macOS et Linux, next-devtools-mcp 0.4.0 cherche d'abord les processus nommés exactement next-server. Sur notre Mac, le processus s'appelle next-server (v16.4.6), donc cette correspondance échouait, et le paquet se rabattait sur le sondage des ports 3000 à 3010. Un serveur de dev sur n'importe quel autre port lui est invisible.
Le correctif est simple. nextjs_call prend le port directement, et cela a fonctionné sur 3417 dès que nous l'avons passé :
{ "port": 3417, "toolName": "get_routes" }
Donc si vous faites tourner plus d'un projet, ou si vous utilisez un port personnalisé, dites-le une fois à l'agent : « le serveur de dev est sur le port 3417 ». Il appellera l'outil avec ce port. Garder les projets entre 3000 et 3010 évite aussi le problème.
Partie 2 : créez votre propre MCP server dans une application Next.js
C'est l'autre sens : votre application Next.js devient quelque chose à laquelle Claude, Cursor ou ChatGPT peuvent se connecter par URL. Les outils typiques sont la recherche dans votre contenu, une requête dans votre base de données ou une action comme la création d'un ticket de support.
Le mcp-handler de Vercel s'occupe du protocole. Il transforme une définition de serveur en une simple fonction (Request) => Response, ce qui correspond exactement à ce qu'exporte un Route Handler Next.js.
La version 2 a beaucoup changé
La plupart des tutoriels montrent encore la version 1, avec Redis, un endpoint SSE et une route dynamique [transport]. La version 2 est plus simple, et les anciens extraits ne fonctionnent pas dessus :
| mcp-handler 1.x | mcp-handler 2.x | |
|---|---|---|
| Paquet SDK | @modelcontextprotocol/sdk 1.x |
@modelcontextprotocol/server 2.x |
| zod | 3 | 4.2 ou ultérieur |
| Node.js | 20 ou ultérieur | |
| Transports | Streamable HTTP et SSE | Streamable HTTP uniquement, sans état |
| Redis | Nécessaire pour SSE | Non utilisé |
| Options de routage | basePath, maxDuration, redisUrl et autres |
Supprimées : montez le handler sur la route de votre choix |
Si vous restez en 1.x, gardez @modelcontextprotocol/sdk en 1.26.0 ou ultérieur. Le README de mcp-handler signale une vulnérabilité de sécurité dans les versions antérieures du SDK.
Installation
npm install mcp-handler@^2 @modelcontextprotocol/server@^2 zod@^4
La route
Créez app/api/mcp/route.ts. Celle-ci donne aux clients IA une recherche dans des articles de blog. Remplacez le tableau par votre base de données ou votre 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 n'est qu'une convention. Le handler ne regarde jamais le chemin, donc app/mcp/route.ts fonctionne tout aussi bien. Donnez aux clients l'URL complète de la route que vous choisissez.
Définissez serverInfo. Sans cela, notre serveur s'est présenté aux clients sous le nom « mcp-typescript server on vercel », ce que les utilisateurs voient dans la liste des serveurs de leur client.
Testez avec curl
Avec npm run dev en cours d'exécution, ces trois requêtes constituent un aller-retour complet. Nous les avons exécutées sur la route ci-dessus :
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"}}}'
La réponse est revenue sous la forme d'un seul server-sent event avec "serverInfo":{"name":"my-blog","version":"1.0.0"}. Remplacez le corps par {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}} pour voir search_posts avec son JSON Schema, et par celui-ci pour exécuter l'outil :
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_posts","arguments":{"query":"edge"}}}
Nous avons obtenu Caching at the edge (/blog/edge-caching). Un simple GET sur la route a répondu 405, ce qui est attendu : la version 2 est sans état et n'a aucun flux de longue durée à ouvrir.
Pour une vue cliquable plutôt que curl, le MCP Inspector fonctionne aussi : npx @modelcontextprotocol/inspector, puis connectez-vous à http://localhost:3000/api/mcp avec le transport Streamable HTTP.
Connectez un client
Les clients qui parlent Streamable HTTP se connectent par 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 lit les serveurs distants dans Settings › Connectors. Pour une URL locale dans claude_desktop_config.json, faites le pont avec mcp-remote :
{
"mcpServers": {
"my-blog": { "command": "npx", "args": ["-y", "mcp-remote", "http://localhost:3000/api/mcp"] }
}
}
Après le déploiement, remplacez l'URL localhost par la vraie, par exemple https://your-app.vercel.app/api/mcp. Notre générateur de configuration écrit ces extraits pour 15 clients si vous y référencez votre serveur.
Protégez-le avant de déployer
Une route déployée est publique. Quiconque trouve l'URL peut appeler vos outils, alors ajoutez l'authentification avant le premier déploiement, pas après.
withMcpAuth enveloppe le handler. Voici la version que nous avons testée, avec un jeton partagé issu d'une variable d'environnement :
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 a son importance. Sans cela, une requête sans jeton valide passe quand même. Avec, notre appel non authentifié a reçu :
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"
et le même appel avec Authorization: Bearer <token> a reçu 200.
Ce lien resource_metadata est ce qui permet aux clients compatibles OAuth de trouver votre page de connexion. Servez-le depuis 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 };
Il a répondu {"resource":"http://localhost:3417","authorization_servers":["https://auth.example.com"]}. Pointez authServerUrls vers votre véritable fournisseur d'identité. Pour de vrais utilisateurs, remplacez le jeton partagé par la vérification des jetons de ce fournisseur, et vérifiez requiredScopes par route. La révision actuelle de la spécification, 2026-07-28, fait passer l'enregistrement des clients de Dynamic Client Registration à Client ID Metadata Documents ; ce travail se fait dans votre serveur d'autorisation, et votre route Next.js ne change pas.
À l'intérieur d'un outil, l'identité vérifiée se trouve sur ctx.http?.authInfo, ce qui permet à un outil de filtrer les résultats selon le compte de l'appelant.
Problèmes et solutions
| Ce que vous voyez | Cause | Correction |
|---|---|---|
[error] No server info found renvoyé par next-devtools-mcp |
Aucun serveur de développement Next.js 16 en cours d'exécution, ou celui-ci se trouve en dehors des ports 3000 à 3010 | Lancez npm run dev ; sur un autre port, indiquez le port à l'agent pour nextjs_call |
ERR_MODULE_NOT_FOUND pour next-devtools-mcp/dist |
Cache npx obsolète | Videz le cache npx et redémarrez le client |
404 sur /_next/mcp |
Next.js 15 ou antérieur, next start, ou experimental.mcpServer: false |
Mettez à niveau, utilisez next dev, ou supprimez le flag |
| L'agent répond à partir des fichiers, n'appelle jamais les outils | Le client n'a pas chargé le serveur | Redémarrez le client et vérifiez sa liste MCP ; dans Claude Code, exécutez /mcp |
405 sur GET /api/mcp |
Normal pour mcp-handler 2 | Rien à corriger ; les clients utilisent POST |
401 avec un en-tête WWW-Authenticate |
withMcpAuth avec required: true et aucun token |
Envoyez Authorization: Bearer ... ou connectez-vous via le flux OAuth du client |
Le code d'un ancien tutoriel échoue sur redisUrl ou basePath |
Écrit pour mcp-handler 1 | Supprimez ces options et montez la route où vous le souhaitez |
| « The module was automatically converted to an EcmaScript module » sur un projet neuf | npm init a ajouté "type": "commonjs" dans package.json |
Supprimez le champ type ; Next.js gère les modules lui-même |
Le dernier cas nous a coûté cinq minutes sur un projet de test vierge. create-next-app n'a pas ce problème.
Les serveurs MCP Next.js dans notre annuaire
Le 14 novembre 2026, le catalogue HostedMCP comptait 19 serveurs actifs portant Next.js dans leur nom, et 4 d'entre eux satisfaisaient à nos règles d'indexation. Les deux qui comptent pour ce guide :
| Serveur | Étoiles | Score de vérification | Ce que c'est |
|---|---|---|---|
| vercel/next-devtools-mcp | 836 | 89 | Le connecteur de la partie 1 |
| vercel-labs/mcp-handler | 699 | 86 | La bibliothèque de la partie 2 |
Les nombres d'étoiles proviennent de GitHub lors de notre dernier rafraîchissement ; le score de vérification est notre examen automatisé du dépôt, de la licence, de la maintenance, de la chaîne d'approvisionnement et des descriptions d'outils, les preuves figurant dans le rapport de vérification de chaque serveur. La plupart des 17 autres sont des modèles de démarrage ou des outils à usage unique avec peu d'étoiles. Vérifiez-les de la même manière avant d'en installer un.
Notes de sécurité
Le point de terminaison de développement est réservé au développement, mais il n'est pas privé. Tant que next dev tourne, tout processus capable d'atteindre le port peut lire le chemin de votre projet, vos routes et l'emplacement des logs. Ne liez pas le serveur de développement à une adresse réseau partagée tant qu'il contient des secrets dans son environnement.
Votre propre route est une API publique dès le jour de son déploiement. Traitez chaque outil comme un point de terminaison : validez les entrées avec le schéma, ne renvoyez que ce que l'appelant est autorisé à voir, et ne placez jamais de secrets ni d'URL internes dans les descriptions d'outils, car le modèle lit ces descriptions, tout comme quiconque liste vos outils. Notre guide de sécurité MCP passe en revue les risques dans l'ordre.
Pour aller plus loin
Si vous voulez les détails du protocole qui sous-tendent cette approche, how to build an MCP server en construit un en TypeScript et en Python purs. Une fois votre serveur en ligne, soumettez le dépôt : HostedMCP le référencera avec des extraits d'installation pour chaque client et exécutera ses vérifications.