my-mcp-server (Vercel · Streamable HTTP)

Next.js App Router 와 mcp-handler 위에서 동작하는 Vercel 배포형 MCP 서버입니다. 기존 StdioServerTransport 기반 로컬 서버를 Streamable HTTP 트랜스포트로 이전하여 임의의 MCP 클라이언트(Cursor, Claude Desktop, MCP Inspector 등) 에서 원격으로 호출할 수 있습니다.

아키텍처

MCP Client (Cursor / Inspector)
       │  Streamable HTTP
       │  + x-hf-token header (선택)
       ▼
Next.js App Router (on Vercel)
  app/api/[transport]/route.ts
       │
       ▼
createMcpHandler ─► McpServer
  ├─ tools: greet / calculate / time / geocode / weather / generate-image
  ├─ prompts: code-review
  └─ resources: server-info

[transport] 동적 세그먼트를 사용해 매 요청마다 핸들러를 새로 만들고, 요청 헤더 (x-hf-token) 와 환경변수(HF_TOKEN) 를 클로저로 캡처해 generate-image 도구에 전달합니다.

프로젝트 구조

.
├── app/
│   ├── api/
│   │   └── [transport]/
│   │       └── route.ts   # MCP HTTP 엔드포인트
│   ├── layout.tsx
│   └── page.tsx           # 안내용 정적 페이지
├── next.config.mjs
├── next-env.d.ts
├── package.json
├── tsconfig.json
└── .env.example

빠른 시작

1. 의존성 설치

npm install

2. 환경변수 설정 (선택)

generate-image 도구를 사용할 계획이라면 .env.example 을 .env.local 로 복사한 뒤 HuggingFace 토큰을 채워 넣습니다.

cp .env.example .env.local
# 그리고 HF_TOKEN=hf_xxx... 로 수정

환경변수가 없어도 클라이언트가 매 요청마다 x-hf-token 헤더를 보내면 동작합니다.

3. 로컬 실행

npm run dev

기본 엔드포인트:

• 안내 페이지: http://localhost:3000
• MCP Streamable HTTP: http://localhost:3000/api/mcp

4. MCP Inspector 로 검증

npx @modelcontextprotocol/inspector@latest

Inspector UI 에서:

1. Transport: Streamable HTTP
2. URL: http://localhost:3000/api/mcp
3. (선택) Custom Headers 에 x-hf-token: hf_xxx... 추가
4. Connect → List Tools → 각 도구 호출 테스트

클라이언트 연결

Cursor (./.cursor/mcp.json)

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

url 만 있으면 5개 도구(greet/calculate/time/geocode/weather)는 정상 동작합니다. generate-image 를 사용하려면 headers.x-hf-token 또는 서버측 HF_TOKEN 환경변수 중 하나가 반드시 필요합니다.

Streamable HTTP 미지원 클라이언트 (mcp-remote 브릿지)

{
    "mcpServers": {
        "my-mcp-server": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "https://<your-app>.vercel.app/api/mcp",
                "--header",
                "x-hf-token:hf_xxx..."
            ]
        }
    }
}

Vercel 배포

방법 1: Vercel CLI

npm i -g vercel
vercel

방법 2: GitHub 연동

1. GitHub 저장소에 푸시
2. https://vercel.com/new 에서 저장소 선택
3. Framework Preset: Next.js (자동 감지)
4. Environment Variables 에서 (선택) HF_TOKEN 추가
5. Deploy

배포가 완료되면 https://<your-app>.vercel.app/api/mcp 가 MCP 엔드포인트입니다.

등록된 도구

이름	설명
greet	이름과 언어(ko/en)로 인사말 생성
calculate	두 숫자 사칙연산 (add/subtract/multiply/divide)
time	타임존별 현재 시간
geocode	Open-Meteo 로 도시명 → 위경도 조회
weather	Open-Meteo 로 위경도 → 현재 날씨 조회
generate-image	HuggingFace FLUX.1-schnell 이미지 생성 (x-hf-token 또는 HF_TOKEN)

프롬프트 / 리소스

• 프롬프트 code-review: 코드를 입력받아 시니어 엔지니어 관점의 체계적 리뷰 메시지 생성
• 리소스 server-info (mcp://my-mcp-server/info): 서버 메타데이터(JSON)

HF_TOKEN 처리 정책

x-hf-token 헤더 ──(있으면 사용)──► HuggingFace Inference
       │ (없음)
       ▼
HF_TOKEN 환경변수 ──(있으면 사용)──► HuggingFace Inference
       │ (없음)
       ▼
generate-image 도구가 명확한 에러 메시지 반환

헤더가 우선이므로 동일 배포 인스턴스를 여러 사용자가 각자의 토큰으로 사용할 수 있습니다.

스크립트

• npm run dev: 로컬 개발 서버
• npm run build: 프로덕션 빌드
• npm run start: 빌드 결과 실행
• npm run lint: Next.js lint

참고 자료

• Deploy MCP servers to Vercel
• vercel/mcp-handler
• Model Context Protocol 공식 문서
• MCP TypeScript SDK

라이선스

MIT