NextJs 16에 새로 추가된 MCP 서버에 알아보자

MCP(Model Context Protocol)란?

MCP는 AI 에이전트와 코딩 어시스턴트가 애플리케이션과 상호작용할 수 있도록 하는 오픈 표준 프로토콜입니다. Next.js는 이를 통해 개발 중인 앱의 상태를 AI가 실시간으로 파악하고 도움을 줄 수 있게 합니다.

---

두 가지 MCP 서버

Next.js는 두 개의 MCP 서버를 함께 사용할 것을 권장합니다:

1️⃣ Next.js MCP 서버 (내장)

Next.js 16 이상에 기본 탑재되어 있으며, 개발 서버 내부에서 실행됩니다.

주요 기능:

• 실시간 앱 상태 접근 - 애플리케이션의 현재 런타임 정보 조회
• 페이지 메타데이터 쿼리 - 라우트, 컴포넌트, 렌더링 세부정보
• 에러 추적 - 빌드 에러, 런타임 에러, 개발 로그 조회
• Server Actions 검사 - 컴포넌트 계층 구조 분석

사용 가능한 도구:

• get_errors - 빌드/런타임/타입 에러 조회
• get_logs - 개발 서버 로그 및 콘솔 출력
• get_page_metadata - 특정 페이지의 라우트, 컴포넌트, 렌더링 정보
• get_project_metadata - 프로젝트 구조, 설정, 전체 메타데이터
• get_server_action_by_id - Server Action ID로 디버깅 정보 조회

2️⃣ Next DevTools MCP (외부 패키지)

별도 npm 패키지로 제공되며, 상위 레벨의 개발 도구와 가이드를 제공합니다.

주요 기능:

• Next.js 지식 베이스 - 공식 문서와 베스트 프랙티스 쿼리
• 마이그레이션 도구 - Next.js 16으로 자동 업그레이드 (codemod 포함)
• Cache Components 가이드 - 캐시 컴포넌트 설정 지원
• 브라우저 테스팅 - Playwright MCP 통합으로 페이지 검증

---

설치 및 설정

기본 설정 (Next.js 16+)

내장 MCP 서버는 자동으로 활성화됩니다. 별도 설정 불필요!

npm run dev  # 개발 서버 시작하면 자동 실행

Next DevTools MCP 추가 설정

프로젝트 루트에 .mcp.json 파일을 만들고 다음 내용을 추가:

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

---

실제 사용 예시

🔍 에러 진단 워크플로우

사용자: "내 앱에 현재 어떤 에러가 있어?"

AI 에이전트 동작:

1. get_errors 도구를 호출
2. 개발 서버에서 빌드/런타임/타입 에러를 가져옴
3. 에러를 분석하고 실행 가능한 해결책 제시

실제 예시:

• /about 페이지에서 하이드레이션 에러 발견
• 서버는 "server"를 렌더링하지만 클라이언트는 "client" 렌더링
• AI가 자동으로 문제 원인 파악 및 수정 방법 제안

🚀 업그레이드 지원

사용자: "Next.js 16으로 업그레이드 도와줘"

AI 에이전트가 수행:

• 현재 버전 분석
• codemod를 통한 자동 마이그레이션 가이드
• Breaking changes 단계별 처리
  • async Request API
  • dynamic route segments
  • route handler 반환 타입

📚 개념 질문

사용자: "App Router에서 'use client'는 언제 써야 해?"

AI 에이전트가 수행:

• next-devtools-mcp를 통해 Next.js 지식 베이스 쿼리
• 공식 문서 기반 설명 제공
• 현재 코드베이스의 실제 예시와 함께 답변

---

AI 에이전트 개발의 장점

MCP를 통해 AI 에이전트는:

✅ 컨텍스트 인식 제안 - 기존 구조를 기반으로 새 기능을 추가할 최적의 위치 추천

✅ 라이브 상태 쿼리 - 개발 중 현재 설정, 라우트, 미들웨어 확인

✅ App Router 레이아웃 이해 - 어떤 페이지와 레이아웃이 렌더링되는지 정확히 파악

✅ 정확한 구현 - 프로젝트의 패턴과 컨벤션을 따르는 코드 생성

---

개발 워크플로우

# 1. Next.js 개발 서버 시작
npm run dev

# 2. AI 코딩 에이전트 연결 (Claude Code, Cursor 등)

# 3. 브라우저에서 애플리케이션 열기

# 4. AI 에이전트에게 인사이트와 진단 요청

---

문제 해결

MCP 서버가 연결되지 않을 때:

1. Next.js v16 이상인지 확인
2. 개발 서버 시작: npm run dev
3. 개발 서버 재시작
4. MCP 클라이언트의 경로 설정 확인
5. AI 에이전트 설정에 MCP 서버 추가 확인

---

핵심 요약

MCP는 AI가 여러분의 Next.js 앱을 "이해"할 수 있게 해주는 다리입니다. 두 개의 MCP 서버를 함께 사용하면:

• Next.js MCP (내장) → 앱 내부 상태를 실시간으로 파악
• Next DevTools MCP (외부) → 개발 가이드와 마이그레이션 도구 제공