MCP 서버 시작하기: Claude Code와 통합하는 첫 번째 도구 만들기

Sun, 03 May 2026 10:47:00 +0900

MCP 서버 시작하기: Claude Code와 통합하는 첫 번째 도구 만들기

MCP(Model Context Protocol)는 Claude Code 및 다른 AI 도구와 통합할 수 있는 강력한 프로토콜입니다. 이 가이드에서는 첫 번째 MCP 서버를 만드는 과정을 단계별로 안내합니다.

MCP란 무엇인가?

MCP는 AI 에이전트가 외부 도구와 리소스에 접근할 수 있게 하는 표준 프로토콜입니다. 주요 특징:

표준화된 인터페이스: 다양한 도구를 통일된 방식으로 통합
리소스 공유: 파일, 데이터베이스 등의 리소스를 안전하게 접근
확장성: 새로운 도구를 쉽게 추가 가능

기본 MCP 서버 구조

// mcp-server-template.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server(
 {
 name: 'my-mcp-server',
 version: '1.0.0'
 },
 {
 capabilities: {
 tools: {},
 resources: {}
 }
 }
);

// 도구 등록 예시
server.setRequestHandler(ListToolsRequestSchema, async () => ({
 tools: [
 {
 name: 'my_tool',
 description: '내 도구 설명',
 inputSchema: {
 type: 'object',
 properties: {
 param1: {
 type: 'string',
 description: '파라미터 설명'
 }
 },
 required: ['param1']
 }
 }
 ]
}));

// 서버 시작
const transport = new StdioServerTransport();
await server.connect(transport);

실전 예제: 간단한 계산기 MCP 서버

// calculator-mcp-server.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';

const server = new Server(
 { name: 'calculator-server', version: '1.0.0' },
 { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
 tools: [
 {
 name: 'calculate',
 description: '기본 수학 연산 수행',
 inputSchema: {
 type: 'object',
 properties: {
 expression: {
 type: 'string',
 description: '계산할 수식 (예: "2 + 2")'
 }
 },
 required: ['expression']
 }
 }
 ]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
 if (request.params.name === 'calculate') {
 const expression = request.params.arguments?.expression as string;
 try {
 // 안전한 계산을 위해 Function 대신 eval 사용
 const result = Function(`"use strict"; return (${expression})`)();
 return {
 content: [{
 type: 'text',
 text: `결과: ${result}`
 }]
 };
 } catch (error) {
 return {
 content: [{
 type: 'text',
 text: `계산 오류: ${error}`
 }],
 isError: true
 };
 }
 }
 return { content: [] };
});

Claude Code 설정

MCP 서버를 Claude Code에 등록하려면 ~/.config/claude/settings.json을 수정합니다:

{
 "mcpServers": {
 "calculator": {
 "command": "node",
 "args": ["/path/to/calculator-mcp-server.js"]
 }
 }
}

리소스 제공하기

// 리소스 리스트 제공
server.setRequestHandler(ListResourcesRequestSchema, async () => ({
 resources: [
 {
 uri: 'calc://history',
 name: '계산 기록',
 description: '최근 계산 이력',
 mimeType: 'application/json'
 }
 ]
}));

// 리소스 내용 제공
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 if (request.params.uri === 'calc://history') {
 return {
 contents: [{
 uri: request.params.uri,
 mimeType: 'application/json',
 text: JSON.stringify({ history: [] })
 }]
 };
 }
 throw new Error('리소스를 찾을 수 없습니다');
});

보안 고려사항

입력 검증: 모든 사용자 입력을 검증하고 제한
권한 제한: 최소 권한 원칙 적용
에러 처리: 민감 정보가 에러 메시지에 노출되지 않도록 주의
속도 제한: 과도한 요청을 방지하는 레이트 리밋 구현

배포 및 테스트

# 서버 빌드
npm run build

# 로컬 테스트
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/server.js

# Claude Code에 통합 후 테스트
# 설정 파일 reload 후 Claude Code에서 도구 사용

다음 단계

더 복잡한 도구와 리소스 추가
프롬프트 템플릿 구현
에러 핸들링 개선
로깅 및 모니터링 추가

MCP 서버 개발은 Claude Code의 기능을 확장하고 자동화를 강화하는 훌륭한 방법입니다. 작은 프로젝트부터 시작하여 점진적으로 기능을 확장해보세요.

Tool-Development on Yarang's Tech Lair

MCP 서버 시작하기: Claude Code와 통합하는 첫 번째 도구 만들기

MCP 서버 시작하기: Claude Code와 통합하는 첫 번째 도구 만들기

MCP란 무엇인가?

기본 MCP 서버 구조

실전 예제: 간단한 계산기 MCP 서버

Claude Code 설정

리소스 제공하기

보안 고려사항

배포 및 테스트

다음 단계

참고 자료