TypeScript MCP Server 보일러플레이트

TypeScript MCP SDK와 mcp-handler를 활용하여 Model Context Protocol (MCP) 서버를 빠르게 개발하고 Vercel에 배포할 수 있는 보일러플레이트 프로젝트입니다.

전송 방식은 Streamable HTTP (/api/mcp)이며, Stdio 대신 Next.js App Router Route Handler로 동작합니다.

프로젝트 구조

typescript-mcp-server-boilerplate/
├── app/
│   ├── api/
│   │   └── [transport]/
│   │       └── route.ts      # MCP HTTP 엔드포인트 (GET/POST/DELETE)
│   ├── layout.tsx
│   └── page.tsx
├── src/
│   └── mcp/
│       ├── context.ts          # x-hf-token 요청 컨텍스트 (AsyncLocalStorage)
│       ├── register.ts         # 도구/리소스/프롬프트 등록
│       └── prompts/
│           └── code-review.ts
├── next.config.ts
├── vercel.json
├── package.json
└── .cursor/mcp.json            # Cursor MCP 연결 예시

시작하기

1. 의존성 설치

npm install

2. 환경 변수 (선택)

로컬에서 서버 측 HF 토큰 fallback을 쓰려면 .env 파일을 만듭니다:

cp .env.example .env
# HF_TOKEN=hf_xxx

클라이언트가 x-hf-token 헤더를내면 헤더 값이 우선되고, 없을 때만 HF_TOKEN 환경변수를 사용합니다.

3. 개발 서버 실행

npm run dev

MCP 엔드포인트: http://localhost:3000/api/mcp

4. 프로덕션 빌드

npm run build
npm run start

등록된 기능

종류	이름	설명
Tool	greeting	이름으로 인사
Tool	calculator	사칙연산 (add/subtract/multiply/divide)
Tool	calculate	연산자 기호 사칙연산
Tool	get_time	시간대별 현재 시각
Tool	generate_image	Hugging Face FLUX 이미지 생성
Tool	geocode	OpenStreetMap Nominatim 지오코딩
Tool	get_weather	Open-Meteo 날씨 조회
Resource	server-info	서버 메타데이터 JSON
Prompt	code_review	코드 리뷰 프롬프트 템플릿

x-hf-token 헤더 (이미지 생성)

generate_image 도구는 Hugging Face API 토큰이 필요합니다.

1. 클라이언트 헤더 (권장): 요청마다 x-hf-token: hf_xxx 전달
2. 서버 환경변수 (fallback): Vercel/로컬에 HF_TOKEN 설정

우선순위: x-hf-token 헤더 → HF_TOKEN 환경변수

Cursor MCP 연결

npm run dev 실행 후 .cursor/mcp.json을 참고하세요:

{
    "mcpServers": {
        "typescript-mcp-server": {
            "url": "http://localhost:3000/api/mcp",
            "headers": {
                "x-hf-token": "YOUR_HUGGING_FACE_TOKEN_HERE"
            }
        }
    }
}

Cursor 0.48+ 에서는 Streamable HTTP URL을 직접 지원합니다.

Stdio 전용 클라이언트 (Claude Desktop 등)

mcp-remote로 HTTP 서버에 프록시합니다:

{
    "mcpServers": {
        "typescript-mcp-server": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "http://localhost:3000/api/mcp",
                "--header",
                "x-hf-token:YOUR_HUGGING_FACE_TOKEN_HERE"
            ]
        }
    }
}

Vercel 배포

1. Vercel에 프로젝트를 연결합니다.
2. Environment Variables에 HF_TOKEN을 추가합니다 (선택, 클라이언트 헤더만 쓸 경우 생략 가능).
3. 배포 후 MCP URL: https://<your-project>.vercel.app/api/mcp

vercel.json에서 MCP Route Handler의 maxDuration을 60초로 설정해 두었습니다. Pro 플랜 이상에서 더 긴 이미지 생성이 필요하면 값을 조정하세요.

배포 후 Cursor 연결 예시

{
    "mcpServers": {
        "typescript-mcp-server": {
            "url": "https://<your-project>.vercel.app/api/mcp",
            "headers": {
                "x-hf-token": "YOUR_HUGGING_FACE_TOKEN_HERE"
            }
        }
    }
}

개발 가이드

MCP 도구 추가하기

src/mcp/register.ts의 registerMcp 함수 안에 server.tool(...) 을 추가합니다.

요청 컨텍스트 사용하기

src/mcp/context.ts의 resolveHfToken()으로 현재 요청의 HF 토큰을 읽을 수 있습니다. Route Handler에서 x-hf-token 헤더를 AsyncLocalStorage에 주입합니다.

주요 의존성

• next: App Router 및 Vercel 배포
• mcp-handler: Vercel용 MCP HTTP 어댑터
• @modelcontextprotocol/sdk: MCP 프로토콜 SDK (1.26.0+)
• @huggingface/inference: 이미지 생성
• zod: 스키마 검증

스크립트

명령	설명
npm run dev	Next.js 개발 서버
npm run build	프로덕션 빌드
npm run start	프로덕션 서버 실행
npm run lint	Next.js 린트

참고 자료

• Vercel - Deploy MCP servers
• vercel/mcp-handler
• Model Context Protocol
• MCP TypeScript SDK

라이선스

MIT