MCP 서버 직접 만들기: Claude에 사내 도구 연결하는 실전 가이드

AI 에이전트가 실제로 일을 하려면 외부 시스템에 접근할 수 있어야 합니다. 사내 DB를 조회하고, 티켓을 생성하고, 배포 상태를 확인하는 식이죠. MCP(Model Context Protocol)는 이 연결을 표준화한 프로토콜로, "AI의 USB-C"라 불리며 OpenAI·Microsoft도 채택한 업계 표준이 되었습니다.

이 글에서는 TypeScript SDK로 실제 동작하는 MCP 서버를 처음부터 만들어 Claude에 연결하는 과정을 다룹니다.

1. MCP가 해결하는 문제

MCP 이전에는 AI에 도구를 붙이려면 플랫폼마다 다른 방식으로 함수 호출(function calling)을 구현해야 했습니다. Claude용, ChatGPT용, 자체 에이전트용 코드를 각각 짜야 했죠.

MCP는 이를 서버-클라이언트 구조로 분리합니다. 한 번 MCP 서버를 만들면 Claude Desktop, Claude Code, 다른 MCP 지원 클라이언트가 모두 같은 서버를 사용할 수 있습니다.

2. 프로젝트 준비

Node.js 18 이상이 필요합니다. 새 프로젝트를 만들고 SDK를 설치합니다.

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node
npx tsc --init

package.json에 ESM 설정을 추가합니다. MCP SDK는 ESM 기반이라 이 설정이 없으면 import 에러가 납니다.

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node build/index.js"
  }
}

3. 가장 단순한 MCP 서버

src/index.ts를 만들고 서버 뼈대를 작성합니다. 핵심은 서버 생성 → 도구 등록 → transport 연결 세 단계입니다.

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: "internal-tools",
  version: "1.0.0",
});

// 도구 등록
server.registerTool(
  "get_order_status",
  {
    title: "주문 상태 조회",
    description: "주문 번호로 현재 배송 상태를 조회합니다.",
    inputSchema: {
      orderId: z.string().describe("조회할 주문 번호 (예: ORD-12345)"),
    },
  },
  async ({ orderId }) => {
    const status = await fetchOrderStatus(orderId); // 사내 API 호출
    return {
      content: [{ type: "text", text: `주문 ${orderId}: ${status}` }],
    };
  }
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  // stdout은 프로토콜 통신용이므로 로그는 반드시 stderr로!
  console.error("MCP server running on stdio");
}

main().catch((err) => {
  console.error("Fatal error:", err);
  process.exit(1);
});

가장 흔한 실수: console.log()를 쓰면 서버가 깨집니다. stdio transport에서 stdout은 JSON-RPC 메시지 전용 채널이기 때문입니다. 로그는 반드시 console.error()(stderr)로 출력하세요.

4. description이 성능을 좌우한다

MCP에서 가장 과소평가되는 부분이 도구 설명(description)입니다. AI는 이 설명만 보고 언제 이 도구를 쓸지 판단합니다. 코드가 아무리 완벽해도 설명이 모호하면 AI가 도구를 안 부르거나 엉뚱하게 씁니다.

파라미터에도 .describe()를 반드시 붙이세요. 형식·예시·제약조건을 함께 적으면 AI의 호출 정확도가 눈에 띄게 올라갑니다.

5. Claude Desktop에 연결하기

빌드 후 설정 파일에 서버를 등록합니다.

npm run build

설정 파일 위치:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "internal-tools": {
      "command": "node",
      "args": ["/절대/경로/my-mcp-server/build/index.js"],
      "env": {
        "API_TOKEN": "your-token-here"
      }
    }
  }
}

반드시 절대 경로를 사용하세요. 상대 경로는 동작하지 않습니다. Claude Desktop을 재시작하면 도구 아이콘에 등록된 도구가 보입니다.

6. 실전 팁: 사내 시스템 연결 시 주의사항

① 권한은 최소한으로

MCP 서버는 AI가 호출하는 코드입니다. AI가 실수하거나 프롬프트 인젝션에 당하면 그 권한으로 실제 작업이 실행됩니다. 읽기 전용으로 시작하고, 쓰기 작업은 정말 필요할 때만 추가하세요. 삭제·결제·배포 같은 비가역적 작업은 사람의 확인 단계를 두는 것이 안전합니다.

② 반환값은 AI가 읽을 수 있게

원시 JSON을 그대로 던지지 말고, AI가 이해하기 쉬운 형태로 가공하세요. 불필요한 필드를 걷어내면 토큰 비용도 함께 절약됩니다.

// 나쁨: 원시 응답 그대로
return { content: [{ type: "text", text: JSON.stringify(rawApiResponse) }] };

// 좋음: 필요한 정보만 정리
return {
  content: [{
    type: "text",
    text: `주문 ${id}\n상태: ${status}\n예상 도착: ${eta}`
  }],
};

③ 에러는 삼키지 말 것

에러가 나면 무엇이 왜 실패했는지 명확히 반환하세요. AI는 그 메시지를 보고 재시도하거나 다른 방법을 찾습니다. "실패했습니다"만 던지면 AI도 사용자도 막힙니다.

7. 어디에 쓸 수 있나

실제 팀에서 유용했던 MCP 서버 아이디어입니다.

• 사내 문서 검색 — Confluence·Notion을 조회해 답변에 근거 제공
• 배포 상태 조회 — "지금 prod에 뭐 올라가 있어?"에 답변
• DB 읽기 전용 쿼리 — 분석용 SELECT만 허용 (쓰기 차단)
• 이슈 트래커 연동 — Jira 티켓 생성·조회
• 로그 검색 — 장애 시 관련 로그를 AI가 직접 찾아 분석

마치며

MCP의 진짜 가치는 한 번 만들면 어디서든 쓸 수 있다는 것입니다. Claude Desktop에서 쓰던 서버를 Claude Code에서도, 다른 MCP 클라이언트에서도 그대로 재사용할 수 있습니다.

시작은 작게 하세요. 읽기 전용 도구 하나부터 만들어 팀에서 실제로 쓰이는지 확인한 뒤 확장하는 것이 가장 빠른 길입니다.

※ MCP SDK는 활발히 개발 중이므로, 최신 API는 공식 문서를 함께 확인하시기 바랍니다.