Next.js MCP Server with Vercel MCP Handler and Descope Node SDK

Introduction

This example shows how to build an MCP server using the Vercel MCP Handler with Descope's Node SDK for session validation. The server provides a simple echo tool and demonstrates how to integrate Descope authentication with the Model Context Protocol (MCP) using Vercel's serverless functions.

Key Components

• Vercel's mcp-handler: Handles the MCP protocol communication and serverless function deployment
• Descope Node SDK: Validates user sessions and provides authentication context
• Echo Tool: A simple example tool that returns a "Hello, world!" message

Deployment

You can connect to the server using the MCP Inspector or any other MCP client. Be sure to include the /api/mcp path in the connection URL.

Requirements

Before proceeding, make sure you have the following:

• Node.js (version 20 or later)
• A valid Descope Project ID

Running the Server

First, add the environment variables in a .env file at the root:

1
NEXT_PUBLIC_DESCOPE_PROJECT_ID=      # Your Descope project ID
2
NEXT_PUBLIC_DESCOPE_BASE_URL=        # Your Descope base URL (optional, defaults to https://api.descope.com)

Then, install dependencies:

1
npm i

Finally, run the server:

1
npm run dev

The server will start on port 3000 (or the port specified in your environment variables).

API Endpoints

• GET/POST /api/[transport]: Handles incoming MCP protocol messages (supports SSE and HTTP transports)

Authentication

The server uses Descope's Node SDK for session validation. The verifyToken function:

1. Extracts the bearer token from the request
2. Uses the Descope Node SDK to validate the session
3. Returns authentication context including user scopes and client ID
4. All MCP endpoints require a valid bearer token

Managing API Keys and OAuth Tokens for Tools

If you want Descope to manage your API keys or OAuth tokens for your MCP, you can use functions in the Node SDK to fetch outbound app tokens at either a user or tenant level:

1
// Fetch user token with specific scopes
2
const userToken =
3
  await descopeClient.management.outboundApplication.fetchTokenByScopes(
4
    "my-app-id",
5
    "user-id",
6
    ["read", "write"],
7
    { withRefreshToken: false },
8
    "tenant-id"
9
  );
10

11
// Fetch latest user token
12
const latestUserToken =
13
  await descopeClient.management.outboundApplication.fetchToken(
14
    "my-app-id",
15
    "user-id",
16
    "tenant-id",
17
    { forceRefresh: false }
18
  );
19

20
// Fetch tenant token with specific scopes
21
const tenantToken =
22
  await descopeClient.management.outboundApplication.fetchTenantTokenByScopes(
23
    "my-app-id",
24
    "tenant-id",
25
    ["read", "write"],
26
    { withRefreshToken: false }
27
  );
28

29
// Fetch latest tenant token
30
const latestTenantToken =
31
  await descopeClient.management.outboundApplication.fetchTenantToken(
32
    "my-app-id",
33
    "tenant-id",
34
    { forceRefresh: false }
35
  );

Available Tools

• echo: Returns a simple "Hello, world!" message