MCP 서버로 레거시 API를 Claude Code에 연결하기 — TypeScript SDK로 커스텀 서버 처음부터 구현하기

mkdir my-mcp-server && cd my-mcp-server
pnpm init
pnpm add @modelcontextprotocol/sdk zod postgres
pnpm add -D typescript @types/node tsx

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src"]
}

{
  "type": "module",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/index.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-legacy-api",
  version: "1.0.0",
});
 
// tool 등록은 아래 실전 예시에서 다룹니다
 
const transport = new StdioServerTransport();
await server.connect(transport);

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
 
// 서버 시작 전 필수 환경변수 검증
const requiredEnvVars = ["API_BASE_URL", "API_KEY"] as const;
for (const key of requiredEnvVars) {
  if (!process.env[key]) {
    throw new Error(`환경변수 ${key}가 설정되지 않았습니다`);
  }
}
 
const API_BASE = process.env.API_BASE_URL as string;
 
const server = new McpServer({
  name: "order-management-api",
  version: "1.0.0",
});
 
// 주문 조회 tool
server.tool(
  "get_order",
  {
    description:
      "주문 ID로 주문 상세 정보를 조회합니다. 상태, 품목, 배송 정보를 포함합니다.",
    inputSchema: {
      orderId: z.string().describe("조회할 주문 ID (예: ORD-2024-00123)"),
    },
  },
  async ({ orderId }) => {
    try {
      const res = await fetch(`${API_BASE}/orders/${orderId}`, {
        headers: { Authorization: `Bearer ${process.env.API_KEY}` },
      });
 
      if (!res.ok) {
        return {
          content: [
            {
              type: "text",
              text: `주문 조회 실패: ${res.status} ${res.statusText}`,
            },
          ],
          isError: true,
        };
      }
 
      const data = await res.json();
      return {
        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
      };
    } catch (err) {
      // 네트워크 타임아웃, DNS 실패 등 fetch 자체가 던지는 에러 처리
      return {
        content: [
          { type: "text", text: `네트워크 오류: ${(err as Error).message}` },
        ],
        isError: true,
      };
    }
  }
);
 
// 주문 상태 업데이트 tool
server.tool(
  "update_order_status",
  {
    description: "주문의 처리 상태를 변경합니다.",
    inputSchema: {
      orderId: z.string(),
      status: z.enum(["processing", "shipped", "delivered", "cancelled"]),
      note: z.string().optional().describe("상태 변경 사유 (선택)"),
    },
  },
  async ({ orderId, status, note }) => {
    try {
      const res = await fetch(`${API_BASE}/orders/${orderId}/status`, {
        method: "PATCH",
        headers: {
          Authorization: `Bearer ${process.env.API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ status, note }),
      });
 
      if (!res.ok) {
        return {
          content: [
            {
              type: "text",
              text: `상태 변경 실패: ${res.status} ${res.statusText}`,
            },
          ],
          isError: true,
        };
      }
 
      const result = await res.json();
      return {
        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
      };
    } catch (err) {
      return {
        content: [
          { type: "text", text: `네트워크 오류: ${(err as Error).message}` },
        ],
        isError: true,
      };
    }
  }
);
 
const transport = new StdioServerTransport();
await server.connect(transport);

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import postgres from "postgres";
 
// DATABASE_URL 없이 시작하면 바로 에러를 낼 수 있도록
if (!process.env.DATABASE_URL) {
  throw new Error("환경변수 DATABASE_URL이 설정되지 않았습니다");
}
 
const sql = postgres(process.env.DATABASE_URL);
 
const server = new McpServer({ name: "db-query-server", version: "1.0.0" });
 
server.tool(
  "query_orders",
  {
    description: "주문 테이블에서 조건에 맞는 주문 목록을 조회합니다.",
    inputSchema: {
      status: z
        .enum(["pending", "processing", "shipped", "delivered"])
        .optional(),
      limit: z.number().int().min(1).max(100).default(20),
    },
  },
  async ({ status, limit }) => {
    try {
      // 동적 WHERE절도 Parameterized query로 처리
      const rows = status
        ? await sql`SELECT * FROM orders WHERE status = ${status} LIMIT ${limit}`
        : await sql`SELECT * FROM orders LIMIT ${limit}`;
 
      return {
        content: [
          {
            type: "text",
            text: `총 ${rows.length}건 조회됨\n\n${JSON.stringify(rows, null, 2)}`,
          },
        ],
      };
    } catch (err) {
      return {
        content: [
          { type: "text", text: `DB 조회 오류: ${(err as Error).message}` },
        ],
        isError: true,
      };
    }
  }
);
 
const transport = new StdioServerTransport();
await server.connect(transport);

# 빌드
pnpm build
 
# 내 로컬 환경에만 등록
claude mcp add my-order-api -- node /absolute/path/to/dist/index.js
 
# 팀 전체와 공유 (프로젝트 루트에 .mcp.json 생성)
claude mcp add --scope project my-order-api -- node dist/index.js

{
  "mcpServers": {
    "my-order-api": {
      "command": "node",
      "args": ["./mcp-server/dist/index.js"],
      "env": {
        "API_BASE_URL": "https://internal-api.company.com",
        "API_KEY": "${MY_INTERNAL_API_KEY}"
      }
    }
  }
}