Cari "Next.js MCP server" dan Anda akan menemukan dua pekerjaan berbeda yang memakai nama yang sama. Sebagian orang ingin coding agent mereka bisa melihat isi aplikasi Next.js yang sedang mereka bangun: error di halaman, route, masalah build. Sebagian lain ingin mengubah aplikasi Next.js mereka menjadi MCP server, supaya Claude atau ChatGPT bisa memanggil tool yang disediakan situs mereka. Sebagian besar halaman yang kami baca hanya membahas salah satunya dan mencampuradukkan yang lain, dan banyak yang masih menampilkan versi lama library untuk pekerjaan kedua.
Panduan ini membahas keduanya. Kami menjalankan setiap perintah dan contoh kode di bawah ini pada 14 November 2026, dengan Next.js 16.4.6, next-devtools-mcp 0.4.0, mcp-handler 2.4.0, @modelcontextprotocol/server 2.4.0 dan zod 4.6.7, di macOS. Kalau hasilnya berbeda dari dokumentasi, kami sebutkan.
Mana yang Anda butuhkan?
| Anda ingin | Gunakan | Berjalan di | AI mendapatkan |
|---|---|---|---|
| Membiarkan Claude Code, Cursor, atau Codex men-debug aplikasi yang sedang Anda tulis | /_next/mcp bawaan plus next-devtools-mcp |
Mesin Anda, hanya saat next dev |
Error langsung, route, log, pemeriksaan kompilasi, dokumentasi yang sesuai versi |
| Memberi aplikasi AI tools dari produk Anda (pencarian, pesanan, dokumentasi) | Route Anda sendiri dengan mcp-handler |
Di mana pun aplikasi di-deploy | Hanya tools yang Anda tulis |
| Keduanya | Keduanya, tidak saling bentrok |
Kalau Anda belum yakin, kemungkinan besar Anda butuh yang pertama. Cukup satu perintah dan tanpa kode.
Bagian 1: menghubungkan coding agent Anda ke aplikasi Next.js yang sedang berjalan
Apa yang diekspos Next.js 16 di /_next/mcp
Sejak Next.js 16, next dev menjawab request MCP di /_next/mcp. Fitur ini aktif secara default. Kami mengirim tools/list ke sana dengan curl dan mendapat sembilan tool:
| Tool | Yang dikembalikan | Butuh |
|---|---|---|
get_errors |
Error saat ini: validasi next.config, error runtime browser, error build dengan stack yang sudah di-source-map |
Halaman terbuka di browser untuk error runtime |
get_logs |
Path ke file log dev berisi console browser dan output server | |
get_page_metadata |
Apa saja yang berkontribusi pada render halaman saat ini | Halaman terbuka di browser |
get_project_metadata |
Path proyek dan URL dev server | |
get_routes |
Semua route dikelompokkan per appRouter dan pagesRouter, segmen dinamis sebagai [param] |
|
get_server_action_by_id |
File sumber dan nama export sebuah Server Action | |
get_compilation_issues |
Error resolve, module yang hilang, error transform di semua route | Turbopack |
compile_route |
Mengompilasi satu route tanpa me-request-nya | Turbopack |
get_request_insights |
Timeline request terbaru, fetch, dan perilaku cache | experimental.requestInsights |
Server itu menyebut dirinya "Next.js MCP Server" versi 0.2.0. Pada aplikasi uji kami yang punya dua halaman, get_routes mengembalikan persis apa yang kami punya: / dan /api/mcp.
Tool kompilasi adalah keuntungan yang jarang disadari. Agent yang baru saja mengedit tiga file bisa bertanya ke dev server yang sedang berjalan apakah file-file itu bisa dikompilasi, alih-alih menjalankan next build penuh saat kode masih setengah jadi.
Ada dua batasan yang perlu Anda tahu sebelum mengandalkannya. Fitur ini hanya ada di development: kami build aplikasi yang sama dan menjalankan next start, dan /_next/mcp mengembalikan 404. Dan fitur ini butuh Next.js 16. Di versi 15 tidak ada apa pun di path itu; npx @next/codemod@latest upgrade latest adalah jalur upgrade yang disarankan oleh tooling-nya sendiri.
Untuk mematikannya, set experimental.mcpServer ke false di next.config.
Install next-devtools-mcp
Agent Anda tidak berbicara langsung ke /_next/mcp. Paket next-devtools-mcp adalah server stdio kecil yang menemukan dev server yang sedang berjalan dan meneruskan panggilan ke sana. Sejak versi 0.4.0, paket ini menjadi konektor tipis dengan empat tool:
nextjs_indexmendaftar dev server Next.js yang sedang berjalan dan tool yang diekspos masing-masing.nextjs_callmenjalankan salah satu tool tersebut di sebuah server, denganportdantoolNameyang diberikan.nextjs_docsmengarahkan agent ke dokumentasi yang ikut terpasang di Next.js Anda, dinode_modules/next/dist/docs/, supaya jawabannya sesuai versi Anda.browser_evalmengarahkan agent ke CLIagent-browseruntuk memeriksa halaman di browser sungguhan.
Paket ini butuh Node.js 20.19 atau lebih baru. Pilih client Anda:
Claude Code
claude mcp add next-devtools npx next-devtools-mcp@latest
Codex
codex mcp add next-devtools -- npx next-devtools-mcp@latest
Di Windows 11, menurut README, Codex juga butuh env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" } dan startup_timeout_ms = 20_000 di .codex/config.toml.
Gemini CLI
gemini mcp add next-devtools npx next-devtools-mcp@latest
Tambahkan -s user untuk menginstalnya di semua proyek, bukan hanya proyek saat ini.
VS Code dengan Copilot
code --add-mcp '{"name":"next-devtools","command":"npx","args":["-y","next-devtools-mcp@latest"]}'
Cursor, atau client apa pun yang membaca file JSON
{
"mcpServers": {
"next-devtools": {
"command": "npx",
"args": ["-y", "next-devtools-mcp@latest"]
}
}
}
Taruh di .mcp.json pada root proyek untuk dibagikan ke tim lewat git, atau di ~/.cursor/mcp.json khusus untuk Cursor saja.
Semua agent sekaligus
npx add-mcp next-devtools-mcp@latest
add-mcp menulis entri untuk setiap coding agent yang ditemukannya di mesin Anda.
Pastikan berfungsi
Jalankan dulu dev server-nya. Lalu buka halaman yang sedang Anda kerjakan di browser, karena get_errors dan get_page_metadata membaca dari sesi browser yang aktif. Sekarang tanyakan sesuatu ke agent yang hanya diketahui oleh aplikasi yang sedang berjalan:
- "Error apa yang dimiliki aplikasi saat ini?"
- "Daftar semua route dan beri tahu mana yang dinamis."
- "Apakah
/blog/[slug]bisa dikompilasi?"
Di Claude Code Anda akan melihat panggilan seperti nextjs_index lalu nextjs_call dengan toolName: "get_errors". Kalau agent malah menjawab dengan membaca file Anda, berarti ia belum terhubung.
Anda juga bisa memeriksa endpoint-nya tanpa agent sama sekali:
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":{}}'
Daftar tool berarti Next.js baik-baik saja dan masalah apa pun ada di antara agent dan next-devtools-mcp.
Yang kami temui: dev server di port lain
Aplikasi uji kami berjalan di port 3417, karena port 3000 sudah dipakai. nextjs_index tidak menemukannya. Yang ditemukan justru proyek lain yang kebetulan berjalan di port 3000.
Membaca source paketnya menjelaskan alasannya. Di macOS dan Linux, next-devtools-mcp 0.4.0 pertama-tama mencari proses yang namanya persis next-server. Di Mac kami prosesnya bernama next-server (v16.4.6), jadi pencocokan itu gagal, dan paketnya beralih memeriksa port 3000 sampai 3010. Dev server di port lain tidak terlihat olehnya.
Solusinya sederhana. nextjs_call menerima port secara langsung, dan langsung berhasil di 3417 begitu kami memberikannya:
{ "port": 3417, "toolName": "get_routes" }
Jadi kalau Anda menjalankan lebih dari satu proyek, atau memakai port kustom, beri tahu agent sekali: "dev server-nya ada di port 3417". Ia akan memanggil tool dengan port tersebut. Menjaga proyek tetap di rentang 3000 sampai 3010 juga menghindari masalah ini.
Bagian 2: membangun MCP server sendiri di dalam aplikasi Next.js
Ini arti yang lain: aplikasi Next.js Anda menjadi sesuatu yang bisa dihubungkan oleh Claude, Cursor, atau ChatGPT lewat URL. Tool yang umum dipakai adalah pencarian atas konten Anda, lookup ke database, atau aksi seperti membuat tiket dukungan.
mcp-handler dari Vercel mengerjakan bagian protokolnya. Ia mengubah definisi server menjadi fungsi (Request) => Response biasa, yang persis seperti yang diekspor oleh Route Handler Next.js.
Versi 2 banyak berubah
Sebagian besar tutorial masih menampilkan versi 1, dengan Redis, endpoint SSE, dan dynamic route [transport]. Versi 2 lebih sederhana, dan snippet lama tidak jalan di atasnya:
| mcp-handler 1.x | mcp-handler 2.x | |
|---|---|---|
| Paket SDK | @modelcontextprotocol/sdk 1.x |
@modelcontextprotocol/server 2.x |
| zod | 3 | 4.2 atau lebih baru |
| Node.js | 20 atau lebih baru | |
| Transport | Streamable HTTP dan SSE | Hanya Streamable HTTP, stateless |
| Redis | Dibutuhkan untuk SSE | Tidak dipakai |
| Opsi routing | basePath, maxDuration, redisUrl, dan lainnya |
Dihapus: mount handler di route yang Anda mau |
Kalau Anda tetap di 1.x, pertahankan @modelcontextprotocol/sdk di versi 1.26.0 atau lebih baru. README mcp-handler menandai versi SDK sebelumnya karena ada kerentanan keamanan.
Install
npm install mcp-handler@^2 @modelcontextprotocol/server@^2 zod@^4
Route-nya
Buat app/api/mcp/route.ts. Yang ini memberi klien AI pencarian atas blog post. Ganti array-nya dengan database atau CMS Anda.
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 cuma konvensi. Handler tidak pernah melihat path-nya, jadi app/mcp/route.ts juga jalan. Beri klien URL lengkap dari route mana pun yang Anda pilih.
Set serverInfo. Tanpa itu, server kita memperkenalkan diri ke klien sebagai "mcp-typescript server on vercel", dan itulah yang dilihat pengguna di daftar server klien mereka.
Uji dengan curl
Dengan npm run dev berjalan, tiga request ini adalah satu round trip penuh. Kami menjalankannya ke route di atas:
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"}}}'
Jawabannya kembali sebagai satu server-sent event dengan "serverInfo":{"name":"my-blog","version":"1.0.0"}. Ganti body-nya dengan {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}} untuk melihat search_posts beserta JSON Schema-nya, dan dengan yang ini untuk menjalankan tool-nya:
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_posts","arguments":{"query":"edge"}}}
Kami dapat Caching at the edge (/blog/edge-caching). GET biasa ke route itu menjawab 405, dan itu memang wajar: versi 2 stateless dan tidak punya stream berumur panjang untuk dibuka.
Kalau mau tampilan yang bisa diklik alih-alih curl, MCP Inspector juga bisa: npx @modelcontextprotocol/inspector, lalu connect ke http://localhost:3000/api/mcp dengan transport Streamable HTTP.
Hubungkan klien
Klien yang mendukung Streamable HTTP connect lewat 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 membaca remote server dari Settings › Connectors. Untuk URL lokal di claude_desktop_config.json, jembatani dengan mcp-remote:
{
"mcpServers": {
"my-blog": { "command": "npx", "args": ["-y", "mcp-remote", "http://localhost:3000/api/mcp"] }
}
}
Setelah deploy, ganti URL localhost dengan yang asli, misalnya https://your-app.vercel.app/api/mcp. Config builder kami menulis snippet ini untuk 15 klien kalau Anda mendaftarkan server Anda di sana.
Amankan sebelum deploy
Route yang sudah di-deploy itu publik. Siapa pun yang menemukan URL-nya bisa memanggil tool Anda, jadi tambahkan auth sebelum deploy pertama, bukan sesudahnya.
withMcpAuth membungkus handler. Ini versi yang kami uji, dengan satu token bersama dari environment variable:
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 itu penting. Tanpa itu, request tanpa token valid tetap lolos. Dengan itu, panggilan tanpa autentikasi kami dapat:
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"
dan panggilan yang sama dengan Authorization: Bearer <token> dapat 200.
Link resource_metadata itulah cara klien yang mendukung OAuth menemukan halaman sign-in Anda. Sajikan dari 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 };
Ia menjawab {"resource":"http://localhost:3417","authorization_servers":["https://auth.example.com"]}. Arahkan authServerUrls ke identity provider Anda yang sebenarnya. Untuk pengguna nyata, ganti token bersama dengan verifikasi token dari provider tersebut, dan cek requiredScopes per route. Revisi spec saat ini, 2026-07-28, memindahkan registrasi klien dari Dynamic Client Registration ke Client ID Metadata Documents; pekerjaan itu terjadi di authorization server Anda, dan route Next.js Anda tidak berubah.
Di dalam tool, identitas yang sudah diverifikasi ada di ctx.http?.authInfo, jadi sebuah tool bisa memfilter hasil berdasarkan akun pemanggilnya.
Masalah dan solusinya
| Yang Anda lihat | Penyebab | Solusi |
|---|---|---|
[error] No server info found dari next-devtools-mcp |
Tidak ada dev server Next.js 16 yang berjalan, atau port-nya di luar 3000 sampai 3010 | Jalankan npm run dev; kalau pakai port lain, beri tahu agent port-nya untuk nextjs_call |
ERR_MODULE_NOT_FOUND untuk next-devtools-mcp/dist |
Cache npx sudah basi | Bersihkan cache npx lalu restart client |
404 pada /_next/mcp |
Next.js 15 atau lebih lama, next start, atau experimental.mcpServer: false |
Upgrade, pakai next dev, atau hapus flag tersebut |
| Agent menjawab dari file, tidak pernah memanggil tool | Client tidak memuat server | Restart client dan cek daftar MCP-nya; di Claude Code jalankan /mcp |
405 pada GET /api/mcp |
Normal untuk mcp-handler 2 | Tidak ada yang perlu diperbaiki; client memakai POST |
401 dengan header WWW-Authenticate |
withMcpAuth dengan required: true dan tanpa token |
Kirim Authorization: Bearer ... atau login lewat alur OAuth client |
Kode tutorial lama gagal pada redisUrl atau basePath |
Ditulis untuk mcp-handler 1 | Hapus opsi tersebut dan mount route di tempat yang Anda inginkan |
| "The module was automatically converted to an EcmaScript module" pada proyek baru | npm init menambahkan "type": "commonjs" ke package.json |
Hapus field type; Next.js menangani modul sendiri |
Yang terakhir sempat menghabiskan lima menit kami di proyek uji yang masih kosong. create-next-app tidak mengalami masalah ini.
Next.js MCP server di direktori kami
Pada 14 November 2026, katalog HostedMCP memuat 19 server aktif dengan nama Next.js, dan 4 di antaranya lolos aturan indeks kami. Dua yang relevan untuk panduan ini:
| Server | Stars | Skor pemeriksaan | Apa itu |
|---|---|---|---|
| vercel/next-devtools-mcp | 836 | 89 | Konektor dari Bagian 1 |
| vercel-labs/mcp-handler | 699 | 86 | Library dari Bagian 2 |
Jumlah star diambil dari GitHub pada refresh terakhir kami; skor pemeriksaan adalah hasil review otomatis kami atas repository, lisensi, maintenance, supply chain, dan deskripsi tool, dengan buktinya ada di laporan pemeriksaan tiap server. Sebagian besar dari 17 server lainnya adalah starter template atau tool khusus dengan sedikit star. Periksa dengan cara yang sama sebelum Anda install.
Catatan keamanan
Endpoint dev hanya untuk pengembangan, tapi bukan berarti privat. Selama next dev berjalan, proses apa pun yang bisa menjangkau port tersebut dapat membaca path proyek, route, dan lokasi log Anda. Jangan bind dev server ke alamat jaringan bersama selama environment-nya masih menyimpan secret.
Route milik Anda sendiri adalah API publik sejak hari Anda deploy. Perlakukan setiap tool seperti endpoint: validasi input dengan schema, kembalikan hanya yang boleh dilihat pemanggil, dan jangan pernah menaruh secret atau URL internal di deskripsi tool, karena model membaca deskripsi tersebut dan begitu juga siapa pun yang menampilkan daftar tool Anda. Panduan keamanan MCP kami membahas risikonya satu per satu.
Langkah selanjutnya
Kalau Anda ingin tahu detail protokol di balik alur ini, cara membangun MCP server memandu Anda membangunnya dengan TypeScript dan Python biasa. Setelah server Anda live, kirimkan repositorinya dan HostedMCP akan menampilkannya lengkap dengan snippet install untuk tiap client serta menjalankan pemeriksaannya.