MG6 MCP Server

Next.js(App Router) 위에서 Streamable HTTP로 동작하는 MCP 서버입니다. Vercel에 그대로 배포할 수 있습니다.

기존 StdioServerTransport 기반 로컬 서버를 mcp-handler 기반 HTTP 라우트로 옮긴 구조입니다.

구조

app/
  api/mcp/route.ts          MCP 엔드포인트 (GET/POST/DELETE)
  layout.tsx, page.tsx      서버 정보를 보여주는 안내 페이지
src/mcp/
  register.ts               도구·리소스·프롬프트 등록 진입점
  server-info.ts            서버 이름/버전, 커스텀 헤더 이름
  helpers.ts                공용 헬퍼 (fetch, 결과 포맷, 에러 변환 등)
  hf-token.ts               요청 헤더 → 환경변수 순으로 HF 토큰 결정
  tools/                    도구 5종
  resources/                리소스
  prompts/                  프롬프트

실행

npm install
npm run dev     # http://localhost:3000/api/mcp

빌드 및 프로덕션 실행:

npm run build
npm run start

제공 기능

도구	설명
greet	이름과 언어로 인사말 생성
calculate	두 숫자와 연산자로 사칙연산
geocode	도시명 → 위도·경도 (Open-Meteo Geocoding)
get_weather	좌표 → 현재 날씨·일별 예보 (Open-Meteo Forecast)
generate-image	프롬프트 → 이미지 (HuggingFace FLUX.1-schnell)

리소스 mg6://server-info, 프롬프트 code-review도 함께 제공합니다.

HuggingFace 토큰 (x-hf-token)

generate-image는 다음 순서로 토큰을 찾습니다.

1. 요청의 x-hf-token 헤더 — 클라이언트가 자기 토큰을 직접 전달
2. 서버의 HF_TOKEN 환경변수 — 헤더가 없을 때의 기본값

공개 배포라면 HF_TOKEN을 비워 두고 각 클라이언트가 자기 토큰을 헤더로 보내게 하는 편이 안전합니다. 토큰은 요청 처리 중에만 사용되고 저장되지 않습니다.

토큰 발급: https://huggingface.co/settings/tokens

MCP 클라이언트 설정

.cursor/mcp.json:

{
    "mcpServers": {
        "MG6_Server": {
            "url": "http://localhost:3000/api/mcp",
            "headers": {
                "x-hf-token": "hf_your_token_here"
            }
        }
    }
}

배포 후에는 url을 https://<your-project>.vercel.app/api/mcp로 바꿉니다.

Streamable HTTP를 지원하지 않는 stdio 전용 클라이언트는 mcp-remote로 연결합니다.

{
    "mcpServers": {
        "MG6_Server": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "http://localhost:3000/api/mcp"]
        }
    }
}

Vercel 배포

1. 저장소를 Vercel 프로젝트로 import 합니다. (프레임워크 자동 감지: Next.js)
2. 서버 기본 토큰을 쓸 경우에만 환경변수 HF_TOKEN을 등록합니다.
3. 배포 후 엔드포인트는 https://<your-project>.vercel.app/api/mcp 입니다.

이미지 생성은 수십 초가 걸릴 수 있어 라우트에 maxDuration = 60을 지정해 두었습니다. 더 긴 실행이 필요하면 Fluid compute를 켜고 값을 올리세요.

인스펙터로 확인하기

npm run inspector

인스펙터에서 Transport를 Streamable HTTP로, URL을 http://localhost:3000/api/mcp로 지정합니다. generate-image를 테스트하려면 Configuration에서 x-hf-token 헤더를 추가하세요.

도구 추가하기

src/mcp/tools/에 등록 함수를 만들고 src/mcp/register.ts에서 호출하면 됩니다.

import type { McpServer } from '@modelcontextprotocol/server'
import { z } from 'zod'

import { textOutputSchema, textResult } from '../helpers'

export function registerEcho(server: McpServer) {
    server.registerTool(
        'echo',
        {
            title: '에코',
            description: '입력을 그대로 돌려줍니다.',
            inputSchema: z.object({ message: z.string() }),
            outputSchema: textOutputSchema('에코 결과')
        },
        async ({ message }) => textResult(message)
    )
}

핸들러의 두 번째 인자 ctx로 원본 HTTP 요청에 접근할 수 있습니다. (ctx.http?.req?.headers)

참고

• Vercel: Deploy MCP servers to Vercel
• vercel/mcp-handler
• Model Context Protocol

Weather data by Open-Meteo.com (CC BY 4.0)