Next.js MCP server: uygulamanızı bağlayın ya da kendinizinkini oluşturun

"Next.js MCP server" diye arama yaptığınızda aynı adı paylaşan iki farklı işle karşılaşırsınız. Kimileri kodlama ajanlarının geliştirdikleri Next.js uygulamasının içini görmesini ister: sayfadaki hatalar, rotalar, derleme sorunları. Kimileri ise Next.js uygulamasını bir MCP server'a dönüştürmek, böylece Claude veya ChatGPT'nin sitelerinin sunduğu araçları çağırabilmesini ister. Okuduğumuz sayfaların çoğu birini ele alıp diğerini bulanıklaştırıyor; birçoğu hâlâ ikinci iş için kütüphanenin eski sürümünü gösteriyor.

Bu rehber ikisini de kapsıyor. Aşağıdaki her komutu ve kod örneğini 14 Kasım 2026'da macOS üzerinde Next.js 16.4.6, next-devtools-mcp 0.4.0, mcp-handler 2.4.0, @modelcontextprotocol/server 2.4.0 ve zod 4.6.7 ile çalıştırdık. Sonucun dokümantasyondan farklı olduğu yerlerde bunu belirtiyoruz.

Hangisine ihtiyacınız var?

Şunu istiyorsanız	Bunu kullanın	Nerede çalışır	Yapay zekâ neye erişir
Claude Code, Cursor veya Codex'in yazdığınız uygulamada hata ayıklamasını sağlamak	Yerleşik /_next/mcp ve next-devtools-mcp	Makinenizde, yalnızca next dev sırasında	Canlı hatalar, rotalar, günlükler, derleme kontrolleri, sürümle eşleşen dokümanlar
Yapay zekâ uygulamalarına ürününüzdeki araçları sunmak (arama, siparişler, dokümanlar)	mcp-handler ile kendi rotanız	Uygulamanın dağıtıldığı her yer	Yalnızca sizin yazdığınız araçlar, başka hiçbir şey
İkisi de	İkisi de, birbiriyle çakışmazlar

Emin değilseniz, muhtemelen ilkini istiyorsunuz. Tek bir komut gerektirir ve kod yazmanız gerekmez.

Bölüm 1: kodlama ajanınızı çalışan bir Next.js uygulamasına bağlayın

Next.js 16, /_next/mcp altında neler sunuyor

Next.js 16'dan itibaren next dev, MCP isteklerini /_next/mcp adresinde yanıtlıyor. Bu varsayılan olarak açık. curl ile bu adrese tools/list gönderdik ve dokuz araç geri aldık:

Araç	Ne döndürür	Gereksinim
get_errors	Güncel hatalar: next.config doğrulaması, tarayıcı çalışma zamanı hataları, kaynak eşlemeli yığın izleriyle derleme hataları	Çalışma zamanı hataları için tarayıcıda açık sayfa
get_logs	Tarayıcı konsolu ve sunucu çıktısını içeren geliştirme günlük dosyasının yolu
get_page_metadata	Geçerli sayfa render'ına neyin katkıda bulunduğu	Tarayıcıda açık sayfa
get_project_metadata	Proje yolu ve geliştirme sunucusu URL'si
get_routes	appRouter ve pagesRouter olarak gruplanmış tüm rotalar, dinamik segmentler [param] biçiminde
get_server_action_by_id	Bir Server Action'ın kaynak dosyası ve export adı
get_compilation_issues	Tüm rotalarda resolve hataları, eksik modüller, transform hataları	Turbopack
compile_route	Bir rotayı istek göndermeden derleme	Turbopack
get_request_insights	Son istek zaman çizelgeleri, fetch'ler ve önbellek davranışı	experimental.requestInsights

Sunucu kendini "Next.js MCP Server" sürüm 0.2.0 olarak tanıttı. İki sayfalık test uygulamamızda get_routes tam olarak elimizde olanı döndürdü: / ve /api/mcp.

Derleme araçları sessiz kazananlar. Üç dosyayı yeni düzenlemiş bir ajan, kod yarım kalmışken tam bir next build başlatmak yerine çalışan geliştirme sunucusuna derlenip derlenmediklerini sorabilir.

Buna güvenmeden önce bilmeniz gereken iki sınır var. Yalnızca geliştirme ortamında mevcut: aynı uygulamayı derleyip next start çalıştırdık ve /_next/mcp 404 döndürdü. Ayrıca Next.js 16 gerektiriyor. 15'te o yolda hiçbir şey yok; npx @next/codemod@latest upgrade latest, araçların kendisinin önerdiği yükseltme yolu.

Kapatmak için next.config içinde experimental.mcpServer değerini false yapın.

next-devtools-mcp kurulumu

Ajanınız /_next/mcp ile doğrudan konuşmaz. next-devtools-mcp paketi, çalışan geliştirme sunucularını bulan ve çağrıları onlara ileten küçük bir stdio sunucusudur. 0.4.0 sürümünden itibaren dört araçlı ince bir bağlayıcıdır:

• nextjs_index, çalışan Next.js geliştirme sunucularını ve her birinin sunduğu araçları listeler.
• nextjs_call, bu araçlardan birini bir sunucuda, port ve toolName vererek çalıştırır.
• nextjs_docs, ajanı kurulu Next.js'inizin içinde, node_modules/next/dist/docs/ altında gelen dokümanlara yönlendirir; böylece yanıtlar sürümünüzle eşleşir.
• browser_eval, ajanı sayfaları gerçek bir tarayıcıda kontrol etmesi için agent-browser CLI'ına yönlendirir.

Node.js 20.19 veya daha yenisini gerektirir. İstemcinizi seçin:

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'de Codex ayrıca README'ye göre .codex/config.toml içinde env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" } ve startup_timeout_ms = 20_000 gerektirir.

Gemini CLI

gemini mcp add next-devtools npx next-devtools-mcp@latest

Yalnızca geçerli proje yerine her proje için kurmak isterseniz -s user ekleyin.

Copilot ile VS Code

code --add-mcp '{"name":"next-devtools","command":"npx","args":["-y","next-devtools-mcp@latest"]}'

Cursor veya JSON dosyası okuyan herhangi bir istemci

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

Bunu git üzerinden ekiple paylaşmak için proje kökündeki .mcp.json dosyasına, yalnızca Cursor için ise ~/.cursor/mcp.json dosyasına koyun.

Tüm ajanlar aynı anda

npx add-mcp next-devtools-mcp@latest

add-mcp, makinede bulduğu her kodlama ajanı için girdiyi yazar.

Çalıştığını doğrulayın

Önce geliştirme sunucusunu başlatın. Ardından üzerinde çalıştığınız sayfayı tarayıcıda açın, çünkü get_errors ve get_page_metadata canlı tarayıcı oturumlarından okur. Şimdi ajana yalnızca çalışan uygulamanın bildiği bir şey sorun:

• "Uygulamanın şu anda hangi hataları var?"
• "Rotaları listele ve hangilerinin dinamik olduğunu söyle."
• "/blog/[slug] derleniyor mu?"

Claude Code'da nextjs_index ve ardından toolName: "get_errors" ile nextjs_call gibi çağrılar görürsünüz. Ajan bunun yerine dosyalarınızı okuyarak yanıt veriyorsa bağlanmamış demektir.

Uç noktayı herhangi bir ajan olmadan da kontrol edebilirsiniz:

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":{}}'

Bir araç listesi dönmesi Next.js'in sorunsuz olduğu ve sorunun ajan ile next-devtools-mcp arasında olduğu anlamına gelir.

Karşılaştığımız durum: başka portlardaki geliştirme sunucuları

Test uygulamamız 3417 portunda çalışıyordu, çünkü 3000 portu doluydu. nextjs_index onu bulamadı. 3000'de çalışan farklı bir projeyi buldu.

Paketin kaynak kodunu okumak nedenini açıkladı. macOS ve Linux'ta next-devtools-mcp 0.4.0 önce tam olarak next-server adlı süreçleri arar. Bizim Mac'imizde süreç next-server (v16.4.6) olarak adlandırıldığı için bu eşleşme başarısız oldu ve paket 3000 ile 3010 arasındaki portları yoklamaya geçti. Başka herhangi bir porttaki geliştirme sunucusu onun için görünmez.

Çözüm basit. nextjs_call portu doğrudan alır ve portu geçirdiğimiz anda 3417'de çalıştı:

{ "port": 3417, "toolName": "get_routes" }

Yani birden fazla proje çalıştırıyorsanız veya özel bir port kullanıyorsanız ajana bir kez söyleyin: "geliştirme sunucusu 3417 portunda". Aracı o portla çağıracaktır. Projeleri 3000 ile 3010 arasında tutmak da sorunu önler.

Bölüm 2: Next.js uygulaması içinde kendi MCP server'ınızı oluşturun

Bu, diğer anlamı: Next.js uygulamanız, Claude, Cursor veya ChatGPT'nin URL üzerinden bağlanabildiği bir şeye dönüşür. Tipik araçlar, içeriğiniz üzerinde arama, veritabanınızda bir sorgu veya destek talebi oluşturma gibi bir eylemdir.

Vercel'in mcp-handler paketi protokol işini yapar. Bir server tanımını düz bir (Request) => Response fonksiyonuna dönüştürür; bu da tam olarak bir Next.js Route Handler'ın dışa aktardığı şeydir.

Sürüm 2 çok şeyi değiştirdi

Çoğu eğitim hâlâ sürüm 1'i, Redis, bir SSE endpoint'i ve [transport] dinamik route'u ile gösteriyor. Sürüm 2 daha basit ve eski kod parçacıkları onda çalışmıyor:

	mcp-handler 1.x	mcp-handler 2.x
SDK paketi	@modelcontextprotocol/sdk 1.x	@modelcontextprotocol/server 2.x
zod	3	4.2 veya üzeri
Node.js		20 veya üzeri
Taşıyıcılar	Streamable HTTP ve SSE	Yalnızca Streamable HTTP, durumsuz
Redis	SSE için gerekli	Kullanılmıyor
Yönlendirme seçenekleri	basePath, maxDuration, redisUrl ve daha fazlası	Kaldırıldı: handler'ı istediğiniz route'a bağlayın

1.x'te kalırsanız @modelcontextprotocol/sdk paketini 1.26.0 veya üzerinde tutun. mcp-handler README dosyası, daha eski SDK sürümlerini bir güvenlik açığı nedeniyle işaretliyor.

Kurulum

npm install mcp-handler@^2 @modelcontextprotocol/server@^2 zod@^4

Route

app/api/mcp/route.ts dosyasını oluşturun. Bu dosya, AI istemcilerine blog yazıları üzerinde arama sunar. Diziyi veritabanınız veya CMS'inizle değiştirin.

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 yalnızca bir gelenektir. Handler yola hiç bakmaz, dolayısıyla app/mcp/route.ts de aynı şekilde çalışır. İstemcilere seçtiğiniz route'un tam URL'sini verin.

serverInfo değerini ayarlayın. Bunu yapmazsanız, server'ımız istemcilere kendini "mcp-typescript server on vercel" olarak tanıttı; kullanıcıların istemcilerinin server listesinde gördüğü de budur.

curl ile test edin

npm run dev çalışırken bu üç istek tam bir gidiş-dönüştür. Bunları yukarıdaki route'a karşı çalıştırdık:

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"}}}'

Yanıt, "serverInfo":{"name":"my-blog","version":"1.0.0"} içeren tek bir server-sent event olarak geldi. search_posts aracını JSON Schema'sıyla görmek için gövdeyi {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}} ile, aracı çalıştırmak için ise şununla değiştirin:

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_posts","arguments":{"query":"edge"}}}

Caching at the edge (/blog/edge-caching) sonucunu aldık. Route'a düz bir GET isteği 405 yanıtı verdi; bu beklenen bir durum: sürüm 2 durumsuzdur ve açılacak uzun ömürlü bir akışı yoktur.

curl yerine tıklayarak görmek isterseniz MCP Inspector da çalışır: npx @modelcontextprotocol/inspector, ardından Streamable HTTP taşıyıcısıyla http://localhost:3000/api/mcp adresine bağlanın.

Bir istemci bağlayın

Streamable HTTP konuşan istemciler URL üzerinden bağlanır.

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 uzak server'ları Settings › Connectors bölümünden okur. claude_desktop_config.json içinde yerel bir URL için mcp-remote ile köprü kurun:

{
  "mcpServers": {
    "my-blog": { "command": "npx", "args": ["-y", "mcp-remote", "http://localhost:3000/api/mcp"] }
  }
}

Dağıtımdan sonra localhost URL'sini gerçek olanla, örneğin https://your-app.vercel.app/api/mcp ile değiştirin. Server'ınızı orada listelerseniz config builder aracımız bu kod parçacıklarını 15 istemci için yazar.

Dağıtmadan önce koruyun

Dağıtılmış bir route herkese açıktır. URL'yi bulan herkes araçlarınızı çağırabilir, bu yüzden kimlik doğrulamayı ilk dağıtımdan sonra değil önce ekleyin.

withMcpAuth handler'ı sarar. İşte test ettiğimiz sürüm; bir ortam değişkeninden gelen tek bir paylaşılan token ile:

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 önemlidir. Bu olmadan geçerli token'ı olmayan bir istek yine de geçer. Bununla birlikte, kimlik doğrulaması yapılmamış çağrımız şunu aldı:

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"

ve Authorization: Bearer <token> ile yapılan aynı çağrı 200 aldı.

Bu resource_metadata bağlantısı, OAuth destekli istemcilerin oturum açma sayfanızı bulma yoludur. Bunu app/.well-known/oauth-protected-resource/route.ts dosyasından sunun:

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"]} yanıtını verdi. authServerUrls değerini gerçek kimlik sağlayıcınıza yönlendirin. Gerçek kullanıcılar için paylaşılan token'ı, o sağlayıcının token'larının doğrulanmasıyla değiştirin ve her route için requiredScopes değerini kontrol edin. Mevcut spec revizyonu olan 2026-07-28, istemci kaydını Dynamic Client Registration'dan Client ID Metadata Documents'a taşıyor; bu iş yetkilendirme sunucunuzda gerçekleşir ve Next.js route'unuz değişmez.

Bir aracın içinde, doğrulanmış kimlik ctx.http?.authInfo üzerindedir, böylece bir araç sonuçları çağıranın hesabına göre filtreleyebilir.

Sorunlar ve çözümleri

Gördüğünüz	Nedeni	Çözümü
next-devtools-mcp'den [error] No server info found	Çalışan bir Next.js 16 dev sunucusu yok ya da sunucu 3000 ile 3010 aralığının dışında	npm run dev komutunu başlatın; başka bir porttaysa ajana nextjs_call için portu verin
next-devtools-mcp/dist için ERR_MODULE_NOT_FOUND	Eskimiş npx önbelleği	npx önbelleğini temizleyin ve istemciyi yeniden başlatın
/_next/mcp üzerinde 404	Next.js 15 veya daha eski bir sürüm, next start ya da experimental.mcpServer: false	Sürümü yükseltin, next dev kullanın veya bayrağı kaldırın
Ajan dosyalardan yanıt veriyor, araçları hiç çağırmıyor	İstemci sunucuyu yüklemedi	İstemciyi yeniden başlatın ve MCP listesini kontrol edin; Claude Code'da /mcp komutunu çalıştırın
GET /api/mcp üzerinde 405	mcp-handler 2 için normaldir	Düzeltilecek bir şey yok; istemciler POST kullanır
WWW-Authenticate başlığıyla birlikte 401	required: true ile withMcpAuth kullanılmış ve token yok	Authorization: Bearer ... gönderin veya istemcinin OAuth akışıyla oturum açın
Eski eğitim kodu redisUrl veya basePath üzerinde hata veriyor	mcp-handler 1 için yazılmış	Bu seçenekleri kaldırın ve rotayı istediğiniz yere bağlayın
Yeni bir projede "The module was automatically converted to an EcmaScript module"	npm init, package.json dosyasına "type": "commonjs" ekledi	type alanını silin; Next.js modülleri kendisi yönetir

Son madde boş bir test projesinde bize beş dakikaya mal oldu. create-next-app ile bu sorun yaşanmıyor.

Dizinimizdeki Next.js MCP server'ları

14 Kasım 2026 itibarıyla HostedMCP kataloğunda adında Next.js geçen 19 etkin server vardı ve bunlardan 4'ü dizin kurallarımızı geçti. Bu rehber için önemli olan ikisi:

Server	Yıldız	Kontrol puanı	Ne olduğu
vercel/next-devtools-mcp	836	89	1. bölümdeki bağlayıcı
vercel-labs/mcp-handler	699	86	2. bölümdeki kütüphane

Yıldız sayıları son yenilememizdeki GitHub verilerinden geliyor; kontrol puanı ise depo, lisans, bakım, tedarik zinciri ve araç açıklamalarına yönelik otomatik incelememizin sonucu ve kanıtlar her server'ın kontrol raporunda yer alıyor. Diğer 17 server'ın çoğu başlangıç şablonu ya da az yıldızlı, tek amaçlı araçlar. Birini kurmadan önce aynı şekilde kontrol edin.

Güvenlik notları

Geliştirme uç noktası yalnızca geliştirme içindir, ancak özel değildir. next dev çalışırken bağlantı noktasına erişebilen herhangi bir süreç proje yolunuzu, rotalarınızı ve günlük konumunuzu okuyabilir. Ortamında gizli bilgiler barındırırken geliştirme sunucusunu paylaşılan bir ağ adresine bağlamayın.

Kendi rotanız, dağıttığınız günden itibaren genel bir API'dir. Her aracı bir uç nokta gibi ele alın: girdiyi şemayla doğrulayın, yalnızca çağıranın görebileceği verileri döndürün ve araç açıklamalarına asla gizli bilgi veya dahili URL koymayın; çünkü model bu açıklamaları okur, araçlarınızı listeleyen herkes de öyle. MCP güvenlik rehberimiz riskleri sırasıyla ele alıyor.

Sırada ne var

Rotanın arkasındaki protokol ayrıntılarını merak ediyorsanız, MCP server nasıl oluşturulur rehberi bir tanesini saf TypeScript ve Python ile oluşturuyor. Sunucunuz yayına girdiğinde depoyu gönderin; HostedMCP onu her istemci için kurulum snippet'leriyle listeler ve kontrollerini çalıştırır.