Next.js MCP Server with Descope

Next.js MCP Server with Descope is a working example that runs a Model Context Protocol (MCP) server on Vercel serverless functions, combining Vercel's mcp-handler for MCP transport with the Descope Node SDK for session validation. It lives in Descope's official AI repository.

What is the Next.js MCP Server with Descope?

It is a Next.js example project that accepts MCP protocol messages over HTTP and Server-Sent Events, authenticates every request with a Descope bearer token, and exposes a sample tool over the MCP endpoint at the /api/mcp path. Inputs are incoming MCP client requests carrying a bearer token; outputs are MCP tool responses, such as the built-in echo tool returning "Hello, world!". It requires Node.js 20 or later and a valid Descope Project ID, and it deploys to Vercel serverless functions, either through the Deploy with Vercel button or by running locally on port 3000.

Key Features

• Vercel mcp-handler integration — handles MCP protocol communication and serverless function deployment, so the MCP server runs as Vercel functions rather than a long-lived process.
• Descope Node SDK session validation — a verifyToken function extracts the bearer token from the request, validates the session with the Descope Node SDK, and returns authentication context including user scopes and client ID.
• Bearer-token enforcement — all MCP endpoints require a valid bearer token, so unauthenticated tool calls are rejected.
• Dual transport support — GET/POST /api/[transport] accepts incoming MCP protocol messages over both SSE and HTTP transports.
• Echo tool — a single example tool that returns a "Hello, world!" message, serving as a template for adding your own tools.
• Environment-based configuration — NEXT_PUBLIC_DESCOPE_PROJECT_ID is required for deployment, and NEXT_PUBLIC_DESCOPE_BASE_URL is optional, defaulting to https://api.descope.com.
• Outbound app token management — Descope Node SDK management functions (fetchTokenByScopes, fetchToken, fetchTenantTokenByScopes, fetchTenantToken) fetch API keys or OAuth tokens at either user or tenant level, with options such as scope lists, withRefreshToken, and forceRefresh.
• One-click deployment — a Vercel deploy button clones the example from the Descope AI repository and prompts for the Descope Project ID.

Who is it for?

• MCP server builders who need authentication: developers writing Model Context Protocol servers who want every tool call gated behind a validated user session instead of exposing an open endpoint.
• Descope customers: teams already using Descope for identity who want their existing project ID and session tokens to authorize MCP tool calls without building a separate auth layer.
• Next.js and Vercel developers: engineers who prefer deploying serverless API routes on Vercel and want a runnable starting point they can clone, extend, and deploy with their own tools.

What can you do with the Next.js MCP Server with Descope?

• Prototype an authenticated MCP server: clone the example, add the Descope Project ID to the environment, run npm run dev, and connect an MCP client such as the MCP Inspector to the /api/mcp path with a bearer token.
• Replace the echo tool with real tools: use the echo tool as the reference implementation for tools that call downstream APIs behind Descope-validated sessions.
• Delegate outbound credentials to Descope: use the outbound application token functions to retrieve user-level or tenant-level API keys and OAuth tokens, including scoped access with read and write permissions and optional refresh tokens.
• Test MCP clients against a hosted endpoint: deploy to Vercel serverless functions and point any MCP-compatible client at the deployment URL to verify transport and authentication behavior.

How does the example work?

Setup follows three steps: add environment variables to a .env file at the project root, install dependencies with npm i, then start the server with npm run dev, which listens on port 3000 or a port from the environment. When an MCP client connects to the /api/[transport] endpoint it must send a bearer token; the request is validated through the Descope Node SDK before the MCP tool response is returned.

FAQ

What Node.js version does this example require?

It requires Node.js version 20 or later, along with a valid Descope Project ID from the Descope console settings page. Node 20 is specified as a prerequisite before running the environment setup, dependency install, and development server commands.

Which MCP transports does the server support?

The server handles incoming MCP protocol messages through GET/POST /api/[transport] and supports both SSE and HTTP transports. When connecting with the MCP Inspector or any other MCP client, you must include the /api/mcp path in the connection URL.

What tools ship with the example?

Only one tool ships by default: the echo tool, which returns a simple "Hello, world!" message. It demonstrates the tool registration pattern and is intended as a starting point that you replace or extend with your own MCP tools.

Does the MCP server require authentication?

Yes. Every MCP endpoint requires a valid bearer token. The verifyToken function extracts the token from the request, validates the session using the Descope Node SDK, and returns authentication context including user scopes and client ID for downstream authorization decisions.