MCP Vercel

Deploy a remote MCP server on Vercel with Next.js and mcp-handler. Use this skill whenever the user wants to create an MCP server, deploy MCP to Vercel, set...

Security Scan

The skill's requirements and runtime instructions are consistent with its stated purpose (deploying an MCP server on Vercel using Next.js and mcp-handler); nothing in the package attempts to access unrelated credentials or perform unexpected installs.

Purpose & Capability

The name/description match the instructions: the SKILL.md shows how to add a Next.js route using mcp-handler and @modelcontextprotocol/sdk and how to deploy to Vercel. It does not request unrelated binaries, credentials, or config paths.

Instruction Scope

Instructions are focused on creating an MCP route, registering tools, and Vercel deployment. They ask the developer to run npm install and to copy compiled artifacts into the Vercel root if using a root directory. That file-copy guidance implies reading project build outputs (e.g., ../../dist) — this is expected for build/deploy steps but you should ensure those paths do not accidentally reference or expose secrets or unrelated files.

Install Mechanism

This is an instruction-only skill (no install spec). The SKILL.md tells the user to run npm install for public packages (mcp-handler, @modelcontextprotocol/sdk, zod). There are no downloads from arbitrary URLs or automatic install steps performed by the skill itself.

Credentials

The skill declares no required environment variables or credentials. In practice, deploying with the Vercel CLI requires Vercel auth (not requested by this skill) and you may add OAuth tokens for protected tools — the skill does not demand unrelated secrets.

Persistence & Privilege

always is false, the skill is user-invokable and not force-included. There is no instruction to modify other skills or global agent settings.

Assessment

This skill appears coherent for adding an MCP endpoint on Vercel, but before installing/applying it: (1) review the npm packages (mcp-handler, @modelcontextprotocol/sdk, zod) for trustworthiness and recent releases; (2) when registering tools, avoid implementing handlers that perform sensitive data reads or expose secrets — test in a staging project first; (3) deploying to Vercel requires your Vercel account/CLI auth — keep tokens secure and do not paste them into third-party UIs; (4) follow the guidance about root directory and file copying carefully so you don't accidentally include build artifacts that contain secrets; (5) if you intend to expose destructive operations (delete/overwrite) via tools, add proper auth and rate-limiting. Overall the skill is internally consistent, but exercise normal operational caution.

Deploy MCP Server on Vercel

Create a production-ready remote MCP server on Vercel using Next.js and mcp-handler. The server communicates via Streamable HTTP and works with Claude Desktop, claude.ai, Smithery, and any MCP client.

Why this approach

Vercel's serverless functions are ideal for MCP servers because MCP's Streamable HTTP transport is stateless — each request is independent, which maps perfectly to serverless. No persistent connections needed. The mcp-handler package from Vercel handles all the protocol details.

Quick setup

1. Install dependencies

npm install mcp-handler @modelcontextprotocol/sdk zod

2. Create the MCP route

Create app/api/mcp/route.ts:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { createMcpHandler } from 'mcp-handler';
import { z } from 'zod';

const handler = createMcpHandler(
  (server: McpServer) => {
    // Register your tools here
    server.tool(
      'example_tool',
      'What this tool does — be specific',
      { query: z.string().describe('What the parameter is for') },
      { readOnlyHint: true, destructiveHint: false, title: 'Example Tool' },
      async ({ query }) => ({
        content: [{ type: 'text', text: `Result for: ${query}` }],
      }),
    );
  },
  {
    serverInfo: { name: 'my-server', version: '1.0.0' },
  },
  {
    streamableHttpEndpoint: '/api/mcp',
    maxDuration: 60,
  },
);

export { handler as GET, handler as POST, handler as DELETE };

3. Deploy and test

vercel deploy --prod

# Verify
curl -X POST https://your-app.vercel.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'

You should get back serverInfo with your server name and version.

Tool design

Safety annotations (required)

Every tool must have annotations. MCP clients use these to decide how cautiously to invoke tools.

// Read-only (search, get, list, fetch)
{ readOnlyHint: true, destructiveHint: false, title: 'Search Items' }

// Write but not destructive (create, add, update)
{ readOnlyHint: false, destructiveHint: false, title: 'Create Item' }

// Destructive (delete, remove, overwrite)
{ readOnlyHint: false, destructiveHint: true, title: 'Delete Item' }

Parameter descriptions

Every parameter needs a .describe() — this is how MCP clients know what to pass.

{
  query: z.string().describe('Search query text'),
  limit: z.number().optional().default(10).describe('Max results to return'),
  type: z.enum(['artist', 'album', 'track']).describe('Type of content'),
}

MCP prompts (optional but recommended)

Prompt templates improve discoverability on Smithery and give users ready-made starting points.

server.prompt('find_items', 'Search for items by name',
  { name: z.string().describe('Item name') },
  ({ name }) => ({
    messages: [{
      role: 'user' as const,
      content: { type: 'text' as const, text: `Find ${name} and show details` },
    }],
  }),
);

Routing — the streamableHttpEndpoint gotcha

Use streamableHttpEndpoint, NOT basePath:

// CORRECT — endpoint at /api/mcp
{ streamableHttpEndpoint: '/api/mcp' }

// WRONG — creates endpoint at /api/mcp/mcp (doubled path)
{ basePath: '/api/mcp' }

The basePath option appends /mcp to whatever you give it. Since your route file is already at app/api/mcp/route.ts, that creates /api/mcp/mcp.

Vercel deployment pitfalls

Root Directory isolation

If your Vercel project uses a Root Directory (like site/), the deployed function CANNOT access files outside that directory. This means import from '../../dist/' will fail at runtime even if it compiles locally.

Solution: Copy compiled files into the site directory and commit them. Use a prebuild script to keep them in sync:

// scripts/copy-deps.js
const fs = require('fs');
const path = require('path');
const src = path.resolve(__dirname, '../../dist');
const dest = path.resolve(__dirname, '../lib/deps');
fs.mkdirSync(dest, { recursive: true });
for (const file of fs.readdirSync(src)) {
  if (file.endsWith('.js') || file.endsWith('.d.ts')) {
    fs.copyFileSync(path.join(src, file), path.join(dest, file));
  }
}

Add to package.json: "prebuild": "node scripts/copy-deps.js"

Serverless read-only filesystem

Vercel functions run on a read-only filesystem with no home directory. If your code writes files (sessions, temp data), wrap in try/catch:

try {
  fs.mkdirSync(dir, { recursive: true });
  fs.writeFileSync(filepath, data);
} catch {
  // Serverless environment — skip filesystem writes
}

Turbopack CJS/ESM mismatch

If importing CommonJS .js files while the parent package.json doesn't have "type": "module", Turbopack will error. Solution: import from compiled .js files bundled within the site directory, not from TypeScript source files in the parent.

Adding authentication

For OAuth-protected servers, see the mcp-oauth skill which covers the complete OAuth 2.0 PKCE flow with withMcpAuth, including dynamic client registration and token storage.

Publishing to Smithery

After deploying, publish to Smithery for broader distribution:

1. Go to https://smithery.ai/new
2. Enter your MCP server URL
3. Choose a namespace/server-id
4. Smithery scans your tools automatically

If your server requires auth, Smithery will prompt you to connect during scanning.

Reference

• mcp-handler
• MCP TypeScript SDK
• Vercel MCP docs