Next.js TypeScript MCP Server with Adapter

Overview

This starter implements a Model Context Protocol (MCP) server using Next.js and TypeScript, packaged with an MCP Adapter so clients can connect and access contextual resources quickly. The project is optimized for deployment on Vercel (or any Next.js host) and exposes a small set of endpoints that let downstream model clients request, read, and manipulate contextual resources (files, URLs, short-lived secrets, etc.) in a safe, extensible way.

The MCP Adapter in this starter wires the protocol to Next.js route handlers (Edge or Node), handling authentication, request/response translation, and resource lookup. It is intended as a minimal, production-ready scaffold you can extend to add custom tools, access policies, or integrations with cloud stores and secrets managers.

Features

• TypeScript-first Next.js implementation (app or pages router)
• Small adapter layer that maps MCP messages to HTTP endpoints
• Built-in example resources (file access, URL fetch, memory store)
• Authentication hooks and API key examples for secure access
• Ready to deploy to Vercel, Netlify, or any platform that supports Next.js
• Extensible tool registry: add custom tools to expose new capabilities

Installation / Configuration

Clone the starter and install dependencies:

git clone https://github.com/vercel-labs/mcp-for-next.js.git
cd mcp-for-next.js
npm install
# or
yarn

Environment variables (example .env.local):

# Basic server settings
PORT=3000
NEXT_PUBLIC_MCP_URL=http://localhost:3000/api/mcp

# A simple API key used by clients to authenticate to the adapter
MCP_API_KEY=your-super-secret-key

# Optional: database or storage configuration
STORAGE_CONNECTION_STRING=...

Run locally:

npm run dev
# or
yarn dev

Deploy to Vercel:

1. Push the repository to GitHub.
2. Connect the repo in Vercel.
3. Add environment variables in the Vercel Dashboard (MCP_API_KEY, STORAGE_CONNECTION_STRING, etc.).
4. Deploy.

Example Next.js adapter route (app router / app/api/mcp/route.ts):

import { NextRequest, NextResponse } from "next/server";
import { createMcpAdapter } from "~/lib/mcp-adapter"; // adapter provided by the starter

const adapter = createMcpAdapter({
  apiKey: process.env.MCP_API_KEY!,
  // optional: hooks for auth, logging, and resource resolution
});

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const result = await adapter.handle(payload);
  return NextResponse.json(result);
}

This route accepts MCP messages from clients, routes them through the adapter, and returns the protocol response.

Available Resources

The starter registers a small set of example resources and tools. These are meant as both examples and useful primitives to expose to model clients:

• file-read: read files from a controlled workspace or storage adapter
• url-fetch: fetch and sanitize HTTP responses (HTML/text) for context ingestion
• memory-store: an ephemeral key-value store for short-lived context
• list-resources: introspect what resources are available and their metadata

Endpoints table

You can extend the resources by implementing the Adapter’s tool interface and registering additional handlers in the server bootstrap file.

Use Cases

• Contextualized LLM calls: Provide models with up-to-date documents or web snippets without embedding all data into the prompt. The model can request resource IDs and the adapter returns sanitized content.
• Private data access: Expose internal documents, short-lived secrets, or internal APIs to model clients under strict access control (API key, scopes, and request logging).
• Multi-model orchestration: Use the MCP server as a shared context layer between multiple models and tools — e.g., a retrieval model requests a document, a generator model builds a response, and a verifier model checks consistency.
• Rapid prototyping: Developers building model-driven features can register quick ad-hoc tools (a URL fetcher, CSV reader, or DB query) and iterate without changing client implementations.

Extending the Starter

• Add new tools: Implement the tool interface in TypeScript and register it with the adapter during initialization.
• Integrate storage: Replace the example file/memory stores with S3, GCS, or a database driver.
• Harden auth: Replace the demo API key with OAuth, JWT, or integration with an identity provider; add scopes and role-based resource policies.
• Observability: Plug in request tracing, structured logging, and audit logs for resource access.

Repository and source

• GitHub: https://github.com/vercel-labs/mcp-for-next.js

This starter is designed to be a compact, extensible foundation for serving contextual resources to