블로그 목록
AI

MCP(Model Context Protocol) 직접 써보기 — Claude에 커스텀 툴 연결하는 법

Claude한테 내 로컬 데이터를 읽게 하거나 사내 API를 직접 호출하게 하고 싶을 때 쓸 수 있는 게 MCP(Model Context Protocol)다. Anthropic에서 공개한 오픈 표준 프로토콜인데, Claude Desktop이나 VS Code 익스텐션에서 공식 지원이 붙으면서 실제로 쓰는 사람이 많아졌다.

구조 자체는 단순하다. MCP 서버를 만들고, Claude Desktop 설정 파일에 등록하면 된다. 서버는 Node.js나 Python으로 짤 수 있다.

MCP 서버 기본 구조

@modelcontextprotocol/sdk를 쓰면 빠르게 시작할 수 있다.

npm install @modelcontextprotocol/sdk zod

// server.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new McpServer({
  name: 'my-mcp-server',
  version: '1.0.0',
});

server.tool(
  'get_weather',
  '도시 이름을 받아서 현재 날씨를 반환합니다',
  { city: z.string().describe('날씨를 조회할 도시 이름') },
  async ({ city }) => {
    const res = await fetch(`https://wttr.in/${city}?format=j1`);
    const data = await res.json();
    const temp = data.current_condition[0].temp_C;
    return {
      content: [{ type: 'text', text: `${city} 현재 기온: ${temp}°C` }],
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

툴은 이름, 설명, 입력 스키마, 핸들러 함수로 구성된다. Zod로 스키마를 정의하면 Claude가 어떤 인자를 넣어야 하는지 자동으로 이해한다.

Claude Desktop에 등록하기

~/Library/Application Support/Claude/claude_desktop_config.json (macOS 기준)에 서버 정보를 추가한다.

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/Users/me/projects/mcp-server/dist/server.js"]
    }
  }
}

Claude Desktop을 재시작하면 좌측 하단에 툴 아이콘이 생기고, 등록된 툴 목록을 확인할 수 있다. 이후 대화에서 "날씨 알려줘"라고 하면 Claude가 알아서 get_weather 툴을 호출한다.

로컬 파일 접근 예제

날씨 API보다 실용적인 예를 들면, 로컬 파일을 읽어오는 툴을 만들 수 있다.

import { readFile } from 'fs/promises';

server.tool(
  'read_file',
  '로컬 파일의 내용을 읽어옵니다',
  { path: z.string().describe('읽을 파일의 절대 경로') },
  async ({ path }) => {
    const content = await readFile(path, 'utf-8');
    return {
      content: [{ type: 'text', text: content }],
    };
  }
);

이렇게 해두면 "이 프로젝트의 package.json 의존성 정리해줘"라고 하면 Claude가 read_file 툴을 호출해서 직접 파일을 읽어온다. 매번 내용을 복사해서 붙여넣지 않아도 된다.

Resources와 Prompts

MCP는 Tools 외에도 두 가지 개념이 더 있다.

Resources는 Claude가 컨텍스트로 참조할 수 있는 데이터 소스다. DB 쿼리 결과나 설정 파일처럼, 대화 흐름과 무관하게 항상 참조 가능한 데이터를 노출할 때 쓴다.

Prompts는 재사용 가능한 프롬프트 템플릿이다. "PR 리뷰 요청" 같은 패턴화된 작업을 미리 정의해두고 /review 같은 슬래시 커맨드로 호출하는 식으로 쓴다.

주의할 점

MCP 서버는 로컬에서 실행된다. 원격 서버에 붙는 게 아니라 내 머신에서 띄운 프로세스와 Claude가 stdin/stdout으로 통신하는 구조다. 그래서 Claude.ai 웹 버전에서는 쓸 수 없고, Claude Desktop이나 MCP를 지원하는 에디터 플러그인에서만 동작한다.

파일 쓰기나 시스템 명령 실행 같은 위험한 툴은 범위를 명확히 제한하는 게 좋다. Claude가 툴을 호출할 때 사용자 확인 없이 바로 실행된다는 점을 기억해야 한다.

설정은 생각보다 간단하다. SDK가 잘 만들어져 있어서 서버 코드 자체는 30줄이면 나온다. 자주 쓰는 사내 API나 데이터 소스를 MCP 서버로 만들어두면 Claude와 협업하는 방식이 꽤 달라진다.

목록으로 돌아가기