Vercel에서 Model Context Protocol 서버 구축하기
Model Context Protocol(MCP)은 AI 시스템을 외부 도구 및 데이터 소스에 연결하기 위한 기본 표준으로 등장했으며, vercel/mcp-handler는 Vercel 플랫폼을 위한 프로덕션 준비 구현을 제공합니다. 이 포괄적인 가이드는 2025년의 최신 업데이트와 모범 사례를 통합하여 개념부터 배포까지 MCP 서버 개발을 탐구합니다.
개발자 관점에서 MCP 이해하기
MCP 서버를 AI 애플리케이션을 위한 특수 API 서버로 생각해보세요. REST API가 웹 클라이언트를 위한 엔드포인트를 노출하는 것처럼, MCP 서버는 AI 모델이 사용할 도구, 리소스 및 프롬프트를 노출합니다. 주요 차이점: 렌더링을 위한 JSON 데이터를 반환하는 대신, AI 모델이 이해하고 행동할 수 있는 구조화된 정보를 반환합니다.
실용적인 분석은 다음과 같습니다:
MCP 서버 = 당신의 API 서버
AI가 호출할 수 있는 함수를 작성합니다. 이들은 API 엔드포인트와 같지만, /api/users와 같은 HTTP 라우트 대신 get_user_data 또는 process_payment와 같은 도구를 정의합니다.
도구 = API 엔드포인트 각 도구는 기본적으로 입력 검증(Zod 스키마 사용)과 반환 값이 있는 함수입니다. Claude나 Gemini가 작업을 수행해야 할 때, 프론트엔드가 API를 호출하는 것처럼 도구를 호출합니다.
리소스 = 정적 데이터 엔드포인트 이들을 컨텍스트 정보를 반환하는 GET 엔드포인트로 생각하세요. 리소스는 정적(구성과 같은) 또는 동적(사용자 프로필과 같은)일 수 있습니다. AI가 참조할 수 있는 읽기 전용 데이터 소스입니다.
프롬프트 = 요청 템플릿 일반적인 AI 작업을 위한 사전 구성된 템플릿입니다 - GraphQL 프래그먼트나 저장된 Postman 요청과 유사합니다. AI 모델이 서버와 상호 작용하는 방식을 표준화하는 데 도움이 됩니다.
vercel/mcp-handler 패키지는 WebSocket 연결, 메시지 라우팅, 오류 처리 등 모든 프로토콜 복잡성을 처리합니다 - 따라서 비즈니스 로직 작성에 집중할 수 있습니다. MCP를 위한 Express.js와 같습니다: 핸들러를 정의하면 프레임워크가 인프라를 관리합니다.
// 이것만 이해하면 됩니다:
// 1. AI가 당신의 도구를 호출
// 2. 요청을 처리
// 3. 응답을 반환
// 나머지는 모두 프레임워크가 처리포괄적인 예제로 vercel/mcp-handler 설정하기
설치는 모든 MCP 서버의 기반을 형성하는 핵심 종속성으로 시작합니다:
npm install mcp-handler @modelcontextprotocol/sdk zod@^3기본 서버 구조는 핸들러 패턴의 우아함을 보여줍니다. 이 Next.js 구현은 필수 구성 요소를 보여주는 간단한 주사위 굴리기 도구를 생성합니다:
// app/api/[transport]/route.ts
import { createMcpHandler } from "mcp-handler";
import { z } from "zod";
const handler = createMcpHandler(
(server) => {
server.tool(
"roll_dice",
"N면 주사위를 굴립니다",
{ sides: z.number().int().min(2).max(100) },
async ({ sides }) => {
const value = 1 + Math.floor(Math.random() * sides);
return {
content: [{ type: "text", text: `🎲 ${value}이(가) 나왔습니다!` }],
};
}
);
},
{
capabilities: {
tools: { roll_dice: { description: "지정된 면수의 주사위 굴리기" } },
},
},
{
redisUrl: process.env.REDIS_URL,
basePath: "/api",
maxDuration: 60,
verboseLogs: process.env.NODE_ENV === "development",
}
);
export { handler as GET, handler as POST, handler as DELETE };구성 객체는 여러 중요한 매개변수를 받습니다. redisUrl은 요청 간 연결 지속성을 유지하기 위한 SSE 전송 상태 관리를 가능하게 합니다. basePath는 라우트 구조와 일치해야 하며, MCP 엔드포인트에 접근할 수 있는 위치를 결정합니다. maxDuration은 연결 시간 초과를 설정하고, verboseLogs는 개발 디버깅을 지원합니다.
프로덕션 환경의 경우 vercel.json 구성이 필수적입니다:
{
"$schema": "https://openapi.vercel.sh/vercel.json",
"functions": {
"api/[transport]/route.ts": {
"maxDuration": 800,
"memory": 1024
}
},
"env": {
"REDIS_URL": "@redis-url",
"MCP_API_KEY": "@mcp-api-key"
}
}도구, 리소스 및 프롬프트 구현하기
도구는 MCP의 주요 상호 작용 메커니즘을 나타내며, AI 모델이 작업을 실행하고 정보를 검색할 수 있도록 합니다. 포괄적인 도구 구현은 검증, 오류 처리 및 응답 형식을 보여줍니다:
server.tool(
"process_data",
"통계 작업으로 데이터셋 분석",
{
data: z.array(z.object({
id: z.string().uuid(),
value: z.number(),
timestamp: z.string().datetime(),
metadata: z.record(z.any()).optional(),
})).min(1, "데이터 배열은 비어 있을 수 없습니다"),
operation: z.enum(["sum", "average", "max", "min", "stddev"]),
groupBy: z.string().optional(),
},
async ({ data, operation, groupBy }) => {
try {
const values = data.map(item => item.value);
let result: number;
switch (operation) {
case "sum":
result = values.reduce((acc, val) => acc + val, 0);
break;
case "average":
result = values.reduce((acc, val) => acc + val, 0) / values.length;
break;
case "stddev":
const mean = values.reduce((a, b) => a + b, 0) / values.length;
const variance = values.reduce((acc, val) =>
acc + Math.pow(val - mean, 2), 0) / values.length;
result = Math.sqrt(variance);
break;
case "max":
result = Math.max(...values);
break;
case "min":
result = Math.min(...values);
break;
}
return {
content: [{
type: "text",
text: `${data.length}개 항목의 ${operation.toUpperCase()}: ${result.toFixed(2)}`
}],
};
} catch (error) {
return {
content: [{
type: "text",
text: `처리 오류: ${error.message}`
}],
isError: true,
};
}
}
);리소스는 AI 모델에 컨텍스트 데이터를 제공하며, 정적 및 동적 콘텐츠를 모두 지원합니다. 동적 리소스 템플릿은 매개변수화된 데이터 액세스를 가능하게 합니다:
import {
ListResourceTemplatesRequestSchema,
ReadResourceRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
server.setRequestHandler(ListResourceTemplatesRequestSchema, () => ({
resourceTemplates: [
{
uriTemplate: "user://{userId}/profile",
name: "사용자 프로필",
description: "환경설정을 포함한 완전한 사용자 프로필",
mimeType: "application/json",
},
{
uriTemplate: "analytics://{metric}/{timeRange}",
name: "분석 데이터",
description: "지정된 메트릭의 시계열 분석",
mimeType: "application/json",
},
],
}));
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
const { uri } = request.params;
const userMatch = uri.match(/^user:\/\/([^\/]+)\/profile$/);
if (userMatch) {
const userId = decodeURIComponent(userMatch[1]);
const userData = await fetchUserFromDatabase(userId);
return {
contents: [{
uri,
text: JSON.stringify(userData, null, 2),
mimeType: "application/json",
}],
};
}
const analyticsMatch = uri.match(/^analytics:\/\/([^\/]+)\/(.+)$/);
if (analyticsMatch) {
const [, metric, timeRange] = analyticsMatch;
const data = await fetchAnalytics(metric, timeRange);
return {
contents: [{
uri,
text: JSON.stringify(data, null, 2),
mimeType: "application/json",
}],
};
}
throw new Error(`리소스를 찾을 수 없음: ${uri}`);
});프롬프트는 일반적인 AI 상호 작용을 위한 재사용 가능한 템플릿을 제공하며, 특히 복잡한 다단계 작업에 유용합니다:
import { GetPromptRequestSchema } from "@modelcontextprotocol/sdk/types.js";
server.setRequestHandler(GetPromptRequestSchema, (request) => {
const { name, arguments: args } = request.params;
if (name === "code-review") {
const { language, code, focus } = args as {
language: string;
code: string;
focus?: string;
};
return {
messages: [
{
role: "user",
content: {
type: "text",
text: `이 ${language} 코드를 검토하세요${focus ? ` (${focus}에 집중)` : ''}:
\`\`\`${language}
${code}
\`\`\`
분석 항목:
- 잠재적 버그 및 엣지 케이스
- 성능 최적화
- 보안 취약점
- 코드 스타일 및 모범 사례
- 권장 리팩토링 개선 사항`,
},
},
],
};
}
throw new Error(`프롬프트를 찾을 수 없음: ${name}`);
});인증 패턴과 보안 구현
보안은 프로덕션 MCP 서버에 대한 중요한 고려 사항입니다. OAuth 2.1 구현은 토큰 오용을 방지하기 위해 Resource Indicators(RFC 8707)를 포함한 최신 표준을 따릅니다:
import { createMcpHandler, withMcpAuth } from "mcp-handler";
import { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
const baseHandler = createMcpHandler((server) => {
server.tool(
"protected_operation",
"민감한 데이터 작업 수행",
{
operation: z.enum(["read", "write", "delete"]),
resource: z.string(),
},
async ({ operation, resource }, extra) => {
const authInfo = extra.authInfo;
// 범위 기반 인증
if (operation === "delete" && !authInfo?.scopes?.includes("admin:delete")) {
return {
content: [{ type: "text", text: "삭제 권한이 부족합니다" }],
isError: true,
};
}
// 사용자 컨텍스트로 작업 실행
const result = await performOperation(operation, resource, authInfo?.clientId);
return {
content: [{
type: "text",
text: `${authInfo?.clientId}에 대한 ${operation}이 완료됨: ${result}`
}],
};
}
);
});
const verifyToken = async (
req: Request,
bearerToken?: string
): Promise<AuthInfo | undefined> => {
if (!bearerToken) return undefined;
try {
// 인증 서버로 토큰 검증
const response = await fetch(process.env.AUTH_SERVER_URL + "/introspect", {
method: "POST",
headers: {
"Content-Type": "application/x-www-form-urlencoded",
"Authorization": `Basic ${Buffer.from(
`${process.env.CLIENT_ID}:${process.env.CLIENT_SECRET}`
).toString("base64")}`,
},
body: new URLSearchParams({
token: bearerToken,
token_type_hint: "access_token",
}),
});
if (!response.ok) return undefined;
const introspection = await response.json();
if (!introspection.active) return undefined;
return {
token: bearerToken,
scopes: introspection.scope?.split(" ") || [],
clientId: introspection.sub,
extra: {
userId: introspection.sub,
organizationId: introspection.org_id,
permissions: introspection.permissions,
},
};
} catch (error) {
console.error("토큰 검증 실패:", error);
return undefined;
}
};
const authHandler = withMcpAuth(baseHandler, verifyToken, {
required: true,
requiredScopes: ["mcp:read", "mcp:execute"],
resourceMetadataPath: "/.well-known/oauth-protected-resource",
});
export { authHandler as GET, authHandler as POST };OAuth 보호 리소스 메타데이터 엔드포인트는 검색 정보를 제공합니다:
// app/.well-known/oauth-protected-resource/route.ts
import { protectedResourceHandler } from "mcp-handler";
const handler = protectedResourceHandler({
authServerUrls: [process.env.AUTH_SERVER_URL],
});
export { handler as GET };Vercel에 특화된 배포 고려 사항
Vercel 플랫폼은 MCP 서버에 대해 서로 다른 트레이드오프를 가진 두 가지 함수 유형을 제공합니다. 서버리스 함수는 완전한 Node.js 런타임 호환성, Enterprise 플랜에서 최대 900초의 긴 실행 제한, 포괄적인 npm 패키지 지원으로 권장되는 접근 방식을 제공합니다. Edge 함수는 40% 더 빠른 콜드 스타트와 15배 낮은 비용을 제공하지만, V8 전용 런타임과 4MB 크기 제한으로 인해 복잡한 MCP 구현에는 적합하지 않습니다.
배포 아키텍처는 불규칙한 사용 패턴을 가진 AI 워크로드에 특히 유익한 기존 서버리스 대비 90% 비용 절감을 위해 Vercel의 Fluid Compute를 활용합니다. 응답성을 유지하기 위해 콜드 스타트 완화 전략이 필수적입니다:
// api/keepalive.js - 콜드 스타트 방지
export default async function handler(req, res) {
// 함수를 웜 상태로 유지하기 위한 간단한 헬스 체크
const timestamp = new Date().toISOString();
res.status(200).json({ status: "warm", timestamp });
}
// vercel.json에서 크론 작업 구성
{
"crons": [{
"path": "/api/keepalive",
"schedule": "*/5 * * * *"
}]
}CORS 구성은 다양한 도메인 간 적절한 클라이언트 연결을 보장합니다:
export const config = {
api: {
cors: {
origin: ["https://claude.ai", "https://cursor.sh", "https://gemini.google.com"],
methods: ["GET", "POST", "OPTIONS"],
allowedHeaders: ["Content-Type", "Authorization", "X-API-Key"],
credentials: true,
}
}
}디버깅, 테스트 및 모니터링 전략
개발은 서버 기능에 대한 즉각적인 피드백을 제공하는 MCP Inspector를 사용한 로컬 테스트로 시작됩니다:
# 개발 서버 시작
vercel dev
# MCP Inspector로 테스트
npx @modelcontextprotocol/inspector http://localhost:3000/api/mcp포괄적인 로깅은 프로덕션 환경에서 디버깅을 용이하게 합니다:
import { createLogger } from "./utils/logger";
const logger = createLogger({
service: "mcp-server",
environment: process.env.VERCEL_ENV,
});
server.tool("complex_operation", "복잡한 처리 수행", schema,
async (args) => {
const requestId = crypto.randomUUID();
logger.info("도구 실행 시작", {
requestId,
tool: "complex_operation",
args: JSON.stringify(args),
});
try {
const result = await performComplexOperation(args);
logger.info("도구 실행 완료", {
requestId,
duration: Date.now() - startTime,
resultSize: JSON.stringify(result).length,
});
return result;
} catch (error) {
logger.error("도구 실행 실패", {
requestId,
error: error.message,
stack: error.stack,
});
throw error;
}
}
);통합 테스트는 엔드투엔드 기능을 검증합니다:
import { describe, it, expect, beforeAll } from "vitest";
import { Client } from "@modelcontextprotocol/sdk/client";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse";
describe("MCP 서버 통합", () => {
let client: Client;
beforeAll(async () => {
client = new Client({
transport: new SSEClientTransport({
url: "http://localhost:3000/api/mcp/sse",
}),
});
await client.connect();
});
it("적절한 검증으로 도구를 실행해야 함", async () => {
const result = await client.callTool({
name: "process_data",
args: {
data: [
{ id: "123e4567-e89b-12d3-a456-426614174000", value: 42, timestamp: new Date().toISOString() },
{ id: "987f6543-e21b-12d3-a456-426614174111", value: 84, timestamp: new Date().toISOString() },
],
operation: "average",
},
});
expect(result.content[0].text).toContain("2개 항목의 AVERAGE: 63.00");
});
});프로덕션 모니터링은 Vercel의 내장 분석과 맞춤 메트릭을 활용합니다:
const metrics = {
toolExecutions: new Map(),
errors: [],
responseTimings: [],
};
const withMetrics = (toolName: string, toolFunction: Function) => {
return async (...args: any[]) => {
const startTime = Date.now();
const executionId = crypto.randomUUID();
metrics.toolExecutions.set(executionId, {
tool: toolName,
startTime,
status: "running",
});
try {
const result = await toolFunction(...args);
const duration = Date.now() - startTime;
metrics.toolExecutions.set(executionId, {
...metrics.toolExecutions.get(executionId),
status: "completed",
duration,
});
metrics.responseTimings.push(duration);
return result;
} catch (error) {
metrics.errors.push({
tool: toolName,
error: error.message,
timestamp: new Date().toISOString(),
});
throw error;
}
};
};실제 사용 사례와 아키텍처 패턴
프로덕션 배포는 산업 전반에 걸친 다양한 MCP 애플리케이션을 보여줍니다. **Block(Square)**는 내부 금융 도구를 위해 60개 이상의 MCP 서버를 운영하며, 결제, 재고 및 분석을 위한 별도 서버로 도메인 주도 설계를 구현합니다. Netflix는 콘텐츠 관리 워크플로우에 MCP를 활용하여 메타데이터, 트랜스코딩 및 추천 시스템을 독립적으로 처리하는 다중 서버 패턴을 사용합니다.
다중 서버 아키텍처 패턴은 관심사를 효과적으로 분리합니다:
// 핵심 비즈니스 로직 서버
const coreServer = createMcpHandler((server) => {
server.tool("create_order", "새 주문 생성", orderSchema,
async (orderData) => {
const order = await createOrder(orderData);
await publishEvent("order.created", order);
return { content: [{ type: "text", text: `주문 ${order.id}가 생성됨` }] };
}
);
});
// 읽기 전용 작업이 있는 분석 서버
const analyticsServer = createMcpHandler((server) => {
server.tool("generate_report", "분석 보고서 생성", reportSchema,
async (params) => {
const report = await generateReport(params);
return { content: [{ type: "text", text: JSON.stringify(report) }] };
}
);
});
// 상승된 권한이 있는 관리 서버
const adminServer = createMcpHandler((server) => {
server.tool("manage_users", "사용자 관리 작업", userManagementSchema,
async (operation, extra) => {
if (!extra.authInfo?.scopes?.includes("admin:users")) {
throw new Error("관리자 권한 필요");
}
const result = await performUserManagement(operation);
return { content: [{ type: "text", text: result }] };
}
);
});서킷 브레이커 패턴은 외부 서비스를 통합할 때 복원력을 보장합니다:
class CircuitBreaker {
private failureCount = 0;
private lastFailureTime?: number;
private state: "CLOSED" | "OPEN" | "HALF_OPEN" = "CLOSED";
constructor(
private threshold = 5,
private timeout = 60000,
private resetTimeout = 120000
) {}
async execute<T>(operation: () => Promise<T>): Promise<T> {
if (this.state === "OPEN") {
if (Date.now() - this.lastFailureTime! > this.resetTimeout) {
this.state = "HALF_OPEN";
this.failureCount = 0;
} else {
throw new Error("서킷 브레이커가 OPEN - 서비스 사용 불가");
}
}
try {
const result = await Promise.race([
operation(),
new Promise<never>((_, reject) =>
setTimeout(() => reject(new Error("작업 시간 초과")), this.timeout)
),
]);
if (this.state === "HALF_OPEN") {
this.state = "CLOSED";
this.failureCount = 0;
}
return result;
} catch (error) {
this.failureCount++;
this.lastFailureTime = Date.now();
if (this.failureCount >= this.threshold) {
this.state = "OPEN";
}
throw error;
}
}
}
const breaker = new CircuitBreaker();
server.tool("external_api_call", "서킷 브레이커로 외부 API 호출", schema,
async (params) => {
try {
const result = await breaker.execute(async () => {
const response = await fetch("https://api.external.com/data", {
method: "POST",
body: JSON.stringify(params),
});
return response.json();
});
return { content: [{ type: "text", text: JSON.stringify(result) }] };
} catch (error) {
return {
content: [{
type: "text",
text: "외부 서비스를 일시적으로 사용할 수 없음 - 나중에 다시 시도하세요"
}],
isError: true,
};
}
}
);최근 업데이트 및 생태계 진화
MCP 생태계는 2024년 11월 출시 이후 폭발적인 성장을 경험했습니다. 2025년 주요 플랫폼 채택에는 3월 Google의 Gemini 데스크톱 및 Agents SDK 전반에 걸친 포괄적인 통합, 5월 Microsoft의 원클릭 서버 연결을 갖춘 네이티브 Copilot Studio 지원, 7월 AWS의 Lambda, ECS 및 기타 서비스용 공식 MCP 서버가 포함됩니다.
보안 개선은 Resource Indicators(RFC 8707)를 사용한 OAuth 2.1 구현, 동작 선언을 위한 강화된 도구 주석, 포괄적인 감사 로깅 기능을 통해 초기 취약점을 해결했습니다. 프로토콜은 이제 텍스트 및 이미지와 함께 오디오 콘텐츠, 향상된 효율성을 위한 JSON-RPC 일괄 처리, 더 이상 사용되지 않는 SSE 메커니즘을 대체하는 Streamable HTTP 전송을 지원합니다.
커뮤니티는 2025년 2월까지 1000개 이상의 MCP 서버를 생성하여 금융 서비스(Stripe, Block)부터 개발자 도구(GitHub, VS Code), 데이터 플랫폼(Databricks, Supabase)까지 다양한 사용 사례에 걸쳐 있습니다. Netflix 및 Block과 같은 회사가 프로덕션 환경에서 수십 개의 서버를 운영하는 기업 배포는 MCP의 프로덕션 준비성을 보여줍니다.
시장 예측에 따르면 MCP 생태계는 2025년 말까지 45억 달러에 도달할 것으로 예상되며, 조직의 90%가 프로토콜을 채택할 것으로 예상됩니다. 기술 진화는 다중 에이전트 조정을 다루는 Google의 Agent2Agent 프로토콜, 확장된 클라우드 플랫폼 통합 및 지속적인 보안 프레임워크 성숙으로 계속됩니다.
모범 사례 및 아키텍처 권장 사항
성공적인 MCP 서버 구현에는 보안, 성능 및 유지 보수성에 대한 세심한 주의가 필요합니다. 보안 우선 설계는 처음부터 OAuth 2.1을 구현하고, Zod 스키마를 사용하여 모든 입력의 유효성을 검사하며, 속도 제한 및 서킷 브레이커를 구현하고, 포괄적인 감사 로그를 유지합니다. Docker 또는 Kubernetes를 사용한 컨테이너 격리는 프로덕션 배포를 위한 추가 보안 경계를 제공합니다.
성능 최적화는 연결 상태 관리를 위해 Redis를 활용하고, 지능형 캐싱 전략을 구현하며, 데이터베이스 액세스에 연결 풀링을 사용하고, 지속적으로 메트릭을 모니터링합니다. 다중 서버 패턴은 읽기 및 쓰기 작업을 분리하고, 무거운 처리 워크로드를 격리하며, 다양한 기능의 독립적인 확장을 가능하게 합니다.
개발 워크플로 모범 사례에는 새 프로젝트를 위해 Streamable HTTP 전송으로 시작하고, 일관된 구현을 위해 공식 SDK를 사용하며, 폴백으로 포괄적인 오류 처리를 구현하고, 통합 테스트를 포함한 높은 테스트 커버리지를 유지하는 것이 포함됩니다. 문서는 API 사양, 인증 요구 사항, 예제 요청 및 응답, 문제 해결 가이드를 다루어야 합니다.
배포 전략은 기능 플래그를 사용한 점진적 출시, 첫날부터 포괄적인 모니터링, 정기적인 보안 감사 및 업데이트, 재해 복구 계획을 우선시합니다. 조직은 위험이 낮은 파일럿 프로그램으로 시작하고, 소규모 배포로 패턴을 검증하며, 입증된 성공을 기반으로 점진적으로 확장해야 합니다.
Model Context Protocol은 AI 시스템이 외부 도구 및 데이터 소스와 상호 작용하는 방식의 근본적인 변화를 나타냅니다. MCP의 사려 깊은 프로토콜 설계와 vercel/mcp-handler의 프로덕션 준비 구현의 조합은 정교한 AI 통합을 구축하기 위한 강력한 기반을 만듭니다. 생태계가 강화된 보안 기능, 더 광범위한 플랫폼 채택 및 입증된 기업 배포로 계속 성숙해짐에 따라 MCP는 차세대 AI 기반 애플리케이션의 표준 프로토콜로 자리매김하고 있습니다.