What is Mcp Adapter

mcp-adapter is a Vercel adapter designed for the Model Context Protocol (MCP), facilitating real-time communication between applications and AI models. It currently supports Next.js, with plans for additional framework adapters in the future.

Use cases

Use cases for mcp-adapter include gaming applications that require random number generation, chatbots that need to process user inputs in real-time, and any application that benefits from dynamic interactions with AI models.

How to use

To use mcp-adapter, install it via npm, yarn, or pnpm. Create an API route for MCP communication in your Next.js application, and utilize the MCP client to make requests to your defined methods.

Key features

Key features of mcp-adapter include real-time communication capabilities, support for Next.js, customizable server options, and integration with Redis for pub/sub functionality.

Where to use

mcp-adapter is suitable for web applications that require real-time interactions with AI models, particularly in environments leveraging Next.js for server-side rendering.

@vercel/mcp-adapter

A Vercel adapter for the Model Context Protocol (MCP), enabling real-time communication between your applications and AI models. Currently supports Next.js with more framework adapters coming soon.

Installation

npm install @vercel/mcp-adapter @modelcontextprotocol/sdk
# or
yarn add @vercel/mcp-adapter @modelcontextprotocol/sdk
# or
pnpm add @vercel/mcp-adapter @modelcontextprotocol/sdk
# or
bun add @vercel/mcp-adapter @modelcontextprotocol/sdk

Next.js Usage

// app/api/[transport]/route.ts
import { createMcpHandler } from "@vercel/mcp-adapter";
const handler = createMcpHandler(
  (server) => {
    server.tool(
      "roll_dice",
      "Rolls an N-sided die",
      {
        sides: z.number().int().min(2),
      },
      async ({ sides }) => {
        const value = 1 + Math.floor(Math.random() * sides);
        return {
          content: [{ type: "text", text: `🎲 You rolled a ${value}!` }],
        };
      }
    );
  },
  {
    // Optional server options
  },
  {
    // Optional redis config
    redisUrl: process.env.REDIS_URL,
    basePath: "/api", // this needs to match where the [transport] is located.
    maxDuration: 60,
    verboseLogs: true,
  }
);
export { handler as GET, handler as POST };

Connecting to your MCP server via stdio

Depending on the version of your client application, remote MCP’s may need to use
mcp-remote to proxy Streamble HTTP into stdio.

If your client supports it, it’s recommended to connect to the Streamable HTTP endpoint directly such as:

"remote-example": {
  "url": "http://localhost:3000/api/mcp",
}

Due to client versions, and varying levels of support, you can list mcp-remote as the method for end users to connect to your MCP server.

The above set up snippet will then look like:

"remote-example": {
  "command": "npx",
  "args": [
    "mcp-remote",
    "-y",
    "http://localhost:3000/api/mcp" // this is your app/api/[transport]/route.ts
  ]
}

Integrating into your client

When you want to use it in your MCP client of choice:

Depending on the version of your client application, remote MCP’s may need to use
mcp-remote to proxy Streamble HTTP into Stdio.

Claude Desktop

Official Docs

In order to add an MCP server to Claude Desktop you need to edit the configuration file located at:

"remote-example": {
  "command": "npx",
  "args": [
    "mcp-remote",
    "-y",
    "http://localhost:3000/api/mcp" // this is your app/api/[transport]/route.ts
  ]
}

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
If it does not exist yet, you may need to enable it under Settings > Developer.

Restart Claude Desktop to pick up the changes in the configuration file. Upon restarting, you should see a hammer icon in the bottom right corner of the input box.

Cursor

Official Docs

The configuration file is located at ~/.cursor/mcp.json.

As of version 0.48.0, Cursor supports unauthed SSE servers directly. If your MCP server is using the official MCP OAuth authorization protocol, you still need to add a “command” server and call mcp-remote.

Windsurf

Official Docs

The configuration file is located at ~/.codeium/windsurf/mcp_config.json.

Usage in your app

1. Use the MCP client in your application:

// app/components/YourComponent.tsx
import { McpClient } from "@modelcontextprotocol/sdk/client";

const client = new McpClient({
  // When using basePath, the SSE endpoint will be automatically derived
  transport: new SSEClientTransport("/api/mcp/mcp"),
});

// Use the client to make requests
const result = await client.request("yourMethod", { param: "value" });

Configuration Options

The initializeMcpApiHandler function accepts the following configuration options:

interface Config {
  redisUrl?: string; // Redis connection URL for pub/sub
  basePath?: string; // string; // Base path for MCP endpoints
  maxDuration?: number; // Maximum duration for SSE connections in seconds
  verboseLogs?: boolean; // Log debugging information
}

Features

• Framework Support: Currently supports Next.js with more framework adapters coming soon
• Multiple Transport Options: Supports both Streamable HTTP and Server-Sent Events (SSE) transports
• Redis Integration: For SSE transport resumability
• TypeScript Support: Full TypeScript support with type definitions

Requirements

• Next.js 13 or later (for Next.js adapter)
• Node.js 18 or later
• Redis (optional, for SSE transport)

License

Apache-2.0