Next.js MCP Server Template

Enables developers to declaratively define AI tools, prompts, and resources that conform to the Model Context Protocol specification through a centralized TypeScript configuration file (app/mcp.ts). Tools are registered with JSON schemas describing input parameters, return types, and descriptions, which are then exposed to MCP clients via standardized protocol endpoints. The system uses the @modelcontextprotocol/sdk to validate and serialize these definitions into protocol-compliant responses.

Implements two distinct communication pathways for MCP clients: stateless HTTP requests via /mcp endpoint for immediate tool invocation, and persistent Server-Sent Events (SSE) connections via /sse endpoint with asynchronous message queueing through /message endpoint. The mcp-api-handler.ts routes incoming requests to appropriate handlers based on transport type, with Redis backing the SSE message queue for distributed state management across serverless instances.

Provides a Redis-based message queue system that decouples SSE client connections from server instances, enabling messages to be published to Redis and consumed by any connected client regardless of which serverless instance handles the request. The system uses Redis pub/sub and list operations to maintain message ordering and delivery guarantees across distributed Next.js instances, with the /message endpoint consuming from the queue and streaming responses back to clients.

Implements a ServerResponseAdapter (lib/server-response-adapter.ts) that normalizes diverse tool execution responses into MCP-compliant protocol format, handling type coercion, error wrapping, and metadata enrichment. The adapter ensures that regardless of how tools are implemented internally (async functions, external APIs, database queries), their responses are serialized into standardized MCP response envelopes with consistent error handling, status codes, and content types.

Leverages Next.js App Router's file-based routing to expose MCP protocol endpoints at /mcp, /sse, and /message routes, with each route handler (route.ts files) implementing specific protocol operations. The routing system automatically handles HTTP method dispatch, request parsing, and response serialization through Next.js middleware and route handlers, eliminating manual Express-style routing configuration.

Provides deployment configuration and patterns optimized for Vercel's Fluid Compute runtime, enabling efficient execution of MCP servers on Vercel's serverless infrastructure with automatic scaling, cost optimization, and Redis integration. The template includes environment variable configuration, deployment scripts, and architectural patterns that leverage Fluid Compute's ability to run longer-duration functions and maintain persistent connections without traditional serverless cold-start penalties.

Provides reference implementations and patterns for building MCP clients that communicate with the Next.js MCP server using both HTTP and SSE transports. The template includes client code demonstrating how to establish connections, send tool invocation requests, handle streaming responses, and manage connection lifecycle, enabling developers to understand the client-side protocol implementation required to interact with the server.

Includes a web-based frontend interface that allows developers to discover available tools, inspect their schemas, and manually invoke them with custom parameters, providing a UI for testing MCP server functionality without requiring external MCP clients. The interface dynamically fetches tool definitions from the server and renders forms for parameter input, displaying results and error messages in real-time.

Leverages TypeScript's type system and JSON Schema integration to provide compile-time and runtime validation of tool parameters and return types. Tool definitions include JSON Schema specifications that are used to validate incoming requests before execution and to type-check tool implementations, ensuring that tools receive correctly-typed parameters and return expected data structures.

Extends the MCP server beyond tool invocation to expose reusable prompts and resources (documents, templates, knowledge bases) through the same protocol, allowing MCP clients to discover and retrieve these assets. Prompts are pre-written instruction templates that can be customized with parameters, while resources are static or dynamic data (files, API responses, database queries) that tools can reference or clients can retrieve directly.