vercel-mcp-template: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is an MCP (Model Context Protocol) server template designed to run on Vercel using serverless functions. It uses the mcp-handler package (v1.0.1) to create MCP servers that expose tools, prompts, and resources via HTTP/SSE transports.

Development Commands

Local development:

vercel dev

Test the MCP server (SSE transport):

node scripts/test-client.mjs https://your-deployment-url.vercel.app
# Or for local testing:
node scripts/test-client.mjs http://localhost:3000

Test the MCP server (Streamable HTTP transport):

node scripts/test-streamable-http-client.mjs https://your-deployment-url.vercel.app

Architecture

Request Flow

Client Request
    ↓
Vercel Edge Network
    ↓
vercel.json rewrites all /(.+) → /api/server
    ↓
api/server.ts exports handler as GET/POST/DELETE
    ↓
mcp-handler routes by HTTP method + path
    ↓
- /mcp → Streamable HTTP transport
- /sse → SSE transport
    ↓
Zod validation → Handler execution → Response

Core Components

api/server.ts - The main MCP server handler. All routes are rewritten to this file via vercel.json. This is where you define MCP tools, prompts, and resources.

Pattern:

import { createMcpHandler } from "mcp-handler";
import { z } from "zod";

const handler = createMcpHandler((server) => {
  // Define tools, prompts, resources here
});

// CRITICAL: Export all three HTTP methods
export { handler as GET, handler as POST, handler as DELETE };

Why all three HTTP methods?

• GET - Used for SSE transport connections and listing operations
• POST - Primary method for tool invocations and MCP protocol requests
• DELETE - Used for cleanup/disconnection operations

mcp-handler - Wraps @modelcontextprotocol/sdk to create a Vercel-compatible serverless MCP server. Internally handles routing, transport negotiation, and protocol operations.