Anthropic MCP TypeScript SDK 완전 가이드: Node.js로 AI 도구 서비스 만들기

저는 HolySheep AI에서 3년간 AI API 통합 업무를 진행하며 수많은 개발자분들이 MCP(Model Context Protocol)를 처음 접할 때 동일한 벽에 부딪히는 것을 지켜봤습니다. 오늘은 그 벽을 깨뜨리는 완벽한 시작 가이드를 만들어보려 합니다. 이 튜토리얼을 마치면 Anthropic MCP TypeScript SDK를 활용해 HolySheep AI의 강력한 Claude 모델과 연동하는 Node.js 도구 서비스를 직접 만들 수 있을 것입니다.

1. MCP(Model Context Protocol)란 무엇인가?

MCP는 AI 모델이 외부 도구나 데이터 소스에 안전하게 접근할 수 있게 하는 개방형 프로토콜입니다. Anthropic에서 개발한 이 프로토콜은 AI 에이전트가 실시간으로 데이터를 조회하고, 외부 API를 호출하고, 복잡한 작업을 자동화할 수 있게 합니다.

MCP의 핵심 개념 3가지

• 호스트(Host): AI 애플리케이션이나 Claude Desktop과 같은 환경입니다.
• 클라이언트(Client): 호스트에 연결되어 도구를 호출하는 SDK입니다.
• 서버(Server): 실제 도구나 리소스를 제공하는 Node.js 서비스입니다.

2. HolySheep AI에서 Claude API 키 발급받기

MCP SDK는 Anthropic API를 사용하므로, 먼저 HolySheep AI에서 API 키를 발급받아야 합니다. HolySheep AI는 Claude Sonnet 4.5를 $15/MTok의 가격으로 제공하며, 해외 신용카드 없이 로컬 결제가 가능합니다.

1. 지금 가입하여 HolySheep AI 계정을 만듭니다.
2. 대시보드에서 API Keys 메뉴로 이동합니다.
3. "Create New Key" 버튼을 클릭하고 키 이름을 입력합니다.
4. 발급된 API 키를 안전한 곳에 저장합니다.

3. 프로젝트 설정하기

먼저 프로젝트 폴더를 만들고 필요한 패키지를 설치합니다.

// 프로젝트 폴더 생성 및 초기화
mkdir mcp-tool-service
cd mcp-tool-service
npm init -y

// TypeScript 및 MCP SDK 설치
npm install typescript @anthropic-ai/sdk @anthropic-ai/mcp-sdk
npm install -D @types/node ts-node nodemon

// tsconfig.json 생성
npx tsc --init

package.json의 dependencies는 다음과 같이 설정됩니다.

{
  "dependencies": {
    "@anthropic-ai/sdk": "^0.52.0",
    "@anthropic-ai/mcp-sdk": "^0.18.0"
  }
}

4. 기본 MCP 서버 만들기

MCP 서버는 AI 모델이 호출할 수 있는 도구를 제공하는 핵심 서비스입니다. 가장 단순한 형태의 서버를 만들어보겠습니다.

import { MCPServer, Tool, ToolResult } from '@anthropic-ai/mcp-sdk';
import { Anthropic } from '@anthropic-ai/sdk';

// HolySheep AI 클라이언트 설정
const client = new Anthropic({
  apiKey: 'YOUR_HOLYSHEEP_API_KEY',
  baseURL: 'https://api.holysheep.ai/v1'
});

// MCP 서버 인스턴스 생성
const server = new MCPServer({
  name: 'my-first-mcp-server',
  version: '1.0.0'
});

// 도구 정의: 현재 시간 조회
const getCurrentTime: Tool = {
  name: 'get_current_time',
  description: '현재 시간을 가져옵니다',
  inputSchema: {
    type: 'object',
    properties: {},
    required: []
  },
  handler: async (params: any): Promise => {
    const now = new Date();
    return {
      content: [
        {
          type: 'text',
          text: 현재 시간은 ${now.toLocaleString('ko-KR')}입니다.
        }
      ]
    };
  }
};

// 도구 정의: 간단한 계산기
const calculator: Tool = {
  name: 'calculate',
  description: '두 숫자의 사칙연산을 수행합니다',
  inputSchema: {
    type: 'object',
    properties: {
      a: { type: 'number', description: '첫 번째 숫자' },
      b: { type: 'number', description: '두 번째 숫자' },
      operation: { 
        type: 'string', 
        enum: ['add', 'subtract', 'multiply', 'divide'],
        description: '연산 종류' 
      }
    },
    required: ['a', 'b', 'operation']
  },
  handler: async (params: any): Promise => {
    const { a, b, operation } = params;
    let result: number;
    let symbol: string;

    switch (operation) {
      case 'add':
        result = a + b;
        symbol = '+';
        break;
      case 'subtract':
        result = a - b;
        symbol = '-';
        break;
      case 'multiply':
        result = a * b;
        symbol = '×';
        break;
      case 'divide':
        if (b === 0) {
          return { 
            content: [{ type: 'text', text: '오류: 0으로 나눌 수 없습니다.' }]
          };
        }
        result = a / b;
        symbol = '÷';
        break;
      default:
        return { content: [{ type: 'text', text: '알 수 없는 연산입니다.' }] };
    }

    return {
      content: [{
        type: 'text',
        text: ${a} ${symbol} ${b} = ${result}
      }]
    };
  }
};

// 도구 등록
server.registerTool(getCurrentTime);
server.registerTool(calculator);

// 서버 시작
server.listen(3000, () => {
  console.log('✅ MCP 서버가 포트 3000에서 실행 중입니다.');
  console.log('   사용 가능한 도구: get_current_time, calculate');
});

// Graceful shutdown
process.on('SIGTERM', async () => {
  console.log('서버를 종료합니다...');
  await server.close();
  process.exit(0);
});

5. MCP 클라이언트로 도구 호출하기

이제 방금 만든 서버의 도구를 호출하는 클라이언트를 만들어보겠습니다. 이 클라이언트는 HolySheep AI의 Claude 모델과 통신하며, 필요할 때 MCP 도구를 자동으로 호출합니다.

import { MCPClient } from '@anthropic-ai/mcp-sdk';
import { Anthropic } from '@anthropic-ai/sdk';
import { SSEClientTransport } from '@anthropic-ai/mcp-sdk/transport';

// HolySheep AI 설정
const client = new Anthropic({
  apiKey: 'YOUR_HOLYSHEEP_API_KEY',
  baseURL: 'https://api.holysheep.ai/v1',
  timeout: 60000,  // 60초 타임아웃
  maxRetries: 3
});

async function main() {
  // MCP 서버에 연결
  const transport = new SSEClientTransport('http://localhost:3000/sse');
  const mcpClient = new MCPClient({ transport });

  console.log('🔗 MCP 서버에 연결 중...');
  await mcpClient.connect();
  console.log('✅ 연결 완료!\n');

  // 사용 가능한 도구 목록 조회
  const tools = await mcpClient.listTools();
  console.log('📦 사용 가능한 도구:');
  tools.forEach(tool => {
    console.log(   - ${tool.name}: ${tool.description});
  });
  console.log('');

  // AI에게 도구 사용 요청
  const userMessage = '42에 8을 더한 결과와 현재 시간을 알려주세요.';

  console.log(💬 사용자: ${userMessage}\n);

  const response = await client.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 1024,
    messages: [
      {
        role: 'user',
        content: userMessage
      }
    ],
    tools: tools.map(tool => ({
      name: tool.name,
      description: tool.description,
      input_schema: tool.inputSchema
    }))
  });

  // 응답 처리
  console.log('🤖 AI 응답:');
  for (const content of response.content) {
    if (content.type === 'text') {
      console.log(   ${content.text});
    } else if (content.type === 'tool_use') {
      console.log(   🔧 도구 호출: ${content.name});
      console.log(   📝 입력값: ${JSON.stringify(content.input)});
      
      // 도구 실행
      const result = await mcpClient.callTool(content.name, content.input);
      console.log(   ✅ 결과: ${JSON.stringify(result)});
    }
  }

  // 연결 종료
  await mcpClient.disconnect();
  console.log('\n👋 연결이 종료되었습니다.');
}

main().catch(console.error);

6. 실전 예제: 데이터베이스 도구 서비스

이제 좀 더 현실적인 사용 사례를 살펴보겠습니다. 데이터베이스를 조회하고 분석하는 MCP 서버를 만들어보겠습니다.

import { MCPServer, Tool, ToolResult } from '@anthropic-ai/mcp-sdk';
import { Anthropic } from '@anthropic-ai/sdk';

// HolySheep AI 설정
const anthropic = new Anthropic({
  apiKey: 'YOUR_HOLYSHEEP_API_KEY',
  baseURL: 'https://api.holysheep.ai/v1'
});

const server = new MCPServer({
  name: 'database-query-server',
  version: '1.0.0'
});

// 가상의 데이터베이스 (실제로는 PostgreSQL, MongoDB 등 사용)
const database = {
  users: [
    { id: 1, name: '김철수', email: '[email protected]', orders: 15, total_spent: 450000 },
    { id: 2, name: '이영희', email: '[email protected]', orders: 8, total_spent: 120000 },
    { id: 3, name: '박지민', email: '[email protected]', orders: 23, total_spent: 890000 }
  ],
  products: [
    { id: 101, name: '노트북', price: 1200000, stock: 5 },
    { id: 102, name: '키보드', price: 89000, stock: 45 },
    { id: 103, name: '마우스', price: 45000, stock: 100 }
  ]
};

// 도구 1: 사용자 조회
const searchUsers: Tool = {
  name: 'search_users',
  description: '사용자를 이름 또는 이메일로 검색합니다',
  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string', description: '검색어 (이름 또는 이메일)' }
    },
    required: ['query']
  },
  handler: async (params: any): Promise => {
    const { query } = params;
    const results = database.users.filter(user => 
      user.name.includes(query) || user.email.includes(query)
    );
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(results, null, 2)
      }]
    };
  }
};

// 도구 2: 인기 상품 조회
const getTopProducts: Tool = {
  name: 'get_top_products',
  description: '가격순으로 상위 N개 상품을 조회합니다',
  inputSchema: {
    type: 'object',
    properties: {
      limit: { type: 'number', description: '조회할 상품 수', default: 5 }
    },
    required: []
  },
  handler: async (params: any): Promise => {
    const limit = params.limit || 5;
    const sorted = [...database.products]
      .sort((a, b) => b.price - a.price)
      .slice(0, limit);
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(sorted, null, 2)
      }]
    };
  }
};

// 도구 3: AI 데이터 분석
const analyzeCustomerData: Tool = {
  name: 'analyze_customer_data',
  description: '고객 데이터를 AI로 분석합니다',
  inputSchema: {
    type: 'object',
    properties: {
      analysis_type: {
        type: 'string',
        enum: ['summary', 'insights', 'recommendations'],
        description: '분석 유형'
      }
    },
    required: ['analysis_type']
  },
  handler: async (params: any): Promise => {
    const { analysis_type } = params;
    
    // HolySheep AI Claude로 분석 수행
    const prompt = `다음 고객 데이터를 ${analysis_type} 관점에서 분석해주세요:
${JSON.stringify(database.users, null, 2)}`;

    const response = await anthropic.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 1024,
      messages: [{ role: 'user', content: prompt }]
    });

    const analysisText = response.content[0].type === 'text' 
      ? response.content[0].text 
      : '분석 결과를 가져올 수 없습니다.';

    return {
      content: [{
        type: 'text',
        text: analysisText
      }]
    };
  }
};

// 도구 등록
server.registerTool(searchUsers);
server.registerTool(getTopProducts);
server.registerTool(analyzeCustomerData);

// 서버 시작
server.listen(3001, () => {
  console.log('📊 데이터베이스 MCP 서버가 포트 3001에서 실행 중입니다.');
  console.log('   도구: search_users, get_top_products, analyze_customer_data');
});

process.on('SIGTERM', async () => {
  await server.close();
  process.exit(0);
});

7. HolySheep AI를 활용한 비용 최적화 팁

저의 경험상 MCP 도구 개발 시 비용 최적화의 핵심은 도구 호출 횟수를 최소화하는 것입니다. HolySheep AI의 Claude Sonnet 4.5는 $15/MTok로 경쟁력 있는 가격을 제공하지만, 효율적인 프롬프트 설계로 비용을 더 줄일 수 있습니다.

비용 최적화 전략 3가지

• 배치 처리: 여러 작업을 한 번의 도구 호출로 처리
• 결과 캐싱: 동일한 쿼리의 결과를 메모리에 저장
• 적절한 모델 선택: 간단한 작업에는 Gemini 2.5 Flash ($2.50/MTok) 활용

8. TypeScript 설정 최적화

MCP SDK를 효과적으로 사용하려면 tsconfig.json을 올바르게 설정해야 합니다.

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

자주 발생하는 오류와 해결책

오류 1: ECONNREFUSED - 서버 연결 실패

// ❌ 오류 메시지
// Error: connect ECONNREFUSED 127.0.0.1:3000

// ✅ 해결 방법: 서버가 먼저 실행되었는지 확인
// 1. 서버를 먼저 시작
node dist/server.js

// 2. 클라이언트 연결 시 연결 대기 추가
async function connectWithRetry(maxRetries = 5) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const transport = new SSEClientTransport('http://localhost:3000/sse');
      const mcpClient = new MCPClient({ transport });
      await mcpClient.connect();
      console.log('연결 성공!');
      return mcpClient;
    } catch (error) {
      console.log(재시도 중... (${i + 1}/${maxRetries}));
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  }
  throw new Error('서버 연결 실패');
}

오류 2: Invalid API Key - 인증 실패

// ❌ 오류 메시지
// Error: Anthropic API error: Invalid API Key

// ✅ 해결 방법: HolySheep AI 키 확인 및 환경 변수 사용
// .env 파일 생성
// HOLYSHEEP_API_KEY=your_actual_api_key_here

// 환경 변수 로드
import * as dotenv from 'dotenv';
dotenv.config();

// 올바른 키 사용 확인
const client = new Anthropic({
  apiKey: process.env.HOLYSHEEP_API_KEY,  // 환경 변수에서 로드
  baseURL: 'https://api.holysheep.ai/v1'  // HolySheep 엔드포인트
});

// 키 유효성 검사 추가
if (!process.env.HOLYSHEEP_API_KEY) {
  throw new Error('HOLYSHEEP_API_KEY가 설정되지 않았습니다.');
}

오류 3: Tool timeout exceeded - 도구 실행 시간 초과

// ❌ 오류 메시지
// Error: Tool execution timeout exceeded

// ✅ 해결 방법: 타임아웃 설정 및 비동기 처리 최적화
const server = new MCPServer({
  name: 'timeout-safe-server',
  version: '1.0.0',
  toolTimeout: 30000  // 30초 타임아웃 설정
});

// 비동기 작업의 타임아웃 감시
async function withTimeout(promise: Promise, timeoutMs: number) {
  const timeout = new Promise((_, reject) => 
    setTimeout(() => reject(new Error('작업 시간 초과')), timeoutMs)
  );
  return Promise.race([promise, timeout]);
}

// 사용 예시
const safeHandler: Tool['handler'] = async (params) => {
  try {
    return await withTimeout(originalHandler(params), 25000);
  } catch (error) {
    return {
      content: [{ type: 'text', text: '작업이 시간 내에 완료되지 못했습니다.' }]
    };
  }
};

오류 4: Malformed tool response - 잘못된 응답 형식

// ❌ 오류 메시지
// Error: Tool response must contain content array

// ✅ 해결 방법: 올바른 ToolResult 형식 반환
// 올바른 형식
const correctHandler: Tool['handler'] = async (params): Promise => {
  return {
    content: [
      { type: 'text', text: '결과 메시지' },
      // 여러 결과도 가능
      { type: 'text', text: '추가 정보' }
    ]
  };
};

// 잘못된 형식들 (피해야 함)
const wrongHandlers = [
  // ❌
관련 리소스
📚 AI API 기술 문서
💰 요금제 보기
📖 개발자 문서
🚀 무료 가입
관련 문서
Gradio AI 데모 HuggingFace Spaces 배포: HolySheep AI 완전 가이드
Prompt 버전管理与 A/B 测试框架：AI 应用プロダクション展開の核心技术
WebSocket 스트리밍 AI 대화: HolySheep AI 전이중 통신 아키텍처实战 가이드