Claude Code에 사내 API 연결하기: TypeScript로 MCP 서버 구현하는 법

pnpm init
pnpm add @modelcontextprotocol/sdk zod
pnpm add -D typescript tsx @types/node

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src"]
}

{
  "type": "module",
  "scripts": {
    "dev": "tsx src/server.ts",
    "build": "tsc",
    "start": "node dist/server.js"
  }
}

// src/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: "company-api-server",
  version: "1.0.0",
});
 
// 사내 직원 정보 API를 Tool로 노출
server.tool(
  "get-employee-info",
  "직원 정보를 사번으로 조회합니다",
  {
    employeeId: z.string().describe("직원 사번 (예: EMP-1234)"),
  },
  async ({ employeeId }) => {
    try {
      const response = await fetch(
        `https://internal-api.company.com/employees/${employeeId}`,
        {
          headers: {
            Authorization: `Bearer ${process.env.INTERNAL_API_TOKEN}`,
          },
        }
      );
 
      if (!response.ok) {
        return {
          content: [
            {
              type: "text",
              text: `오류: 직원 정보를 가져오지 못했습니다 (상태 코드: ${response.status})`,
            },
          ],
          isError: true,
        };
      }
 
      const data = await response.json();
      return {
        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `네트워크 오류: ${error instanceof Error ? error.message : "알 수 없는 오류"}`,
          },
        ],
        isError: true,
      };
    }
  }
);
 
// 사내 프로젝트 목록을 Resource로 노출
server.resource(
  "project-list",
  "internal://projects/active",
  { mimeType: "application/json" },
  async () => {
    const response = await fetch(
      "https://internal-api.company.com/projects?status=active",
      {
        headers: {
          Authorization: `Bearer ${process.env.INTERNAL_API_TOKEN}`,
        },
      }
    );
    const data = await response.json();
    return {
      contents: [
        {
          uri: "internal://projects/active",
          mimeType: "application/json",
          text: JSON.stringify(data, null, 2),
        },
      ],
    };
  }
);
 
const transport = new StdioServerTransport();
await server.connect(transport);

// src/base-server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
 
export function createBaseServer(): McpServer {
  const server = new McpServer({
    name: "base-server",
    version: "1.0.0",
  });
 
  // 오픈소스 서버가 제공하는 기본 Tool
  server.tool(
    "query-database",
    "내부 데이터베이스를 조회합니다",
    { table: z.string().describe("조회할 테이블 이름") },
    async ({ table }) => {
      // ... DB 조회 로직
      return { content: [{ type: "text", text: `${table} 조회 결과` }] };
    }
  );
 
  return server; // 인스턴스를 반환해 외부에서 확장 가능하게 합니다
}

// src/extended-server.ts
import { createBaseServer } from "./base-server.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
 
// 기존 서버 인스턴스를 가져옵니다
const server = createBaseServer();
 
// 사내 기술 문서 검색 Tool을 추가 등록합니다
server.tool(
  "search-internal-docs",
  "사내 기술 문서를 키워드로 검색합니다",
  {
    query: z.string().describe("검색 키워드"),
    category: z
      .enum(["architecture", "runbook", "api-spec", "onboarding"])
      .optional()
      .describe("문서 카테고리 필터"),
  },
  async ({ query, category }) => {
    const params = new URLSearchParams({ q: query });
    if (category) params.set("category", category);
 
    try {
      const response = await fetch(
        `https://docs.internal.company.com/api/search?${params}`,
        {
          headers: { Authorization: `Bearer ${process.env.DOCS_API_TOKEN}` },
        }
      );
 
      if (!response.ok) {
        return {
          content: [
            {
              type: "text",
              text: `오류: 문서 검색 실패 (상태 코드: ${response.status})`,
            },
          ],
          isError: true,
        };
      }
 
      const data = await response.json() as {
        items: Array<{ title: string; url: string; summary: string }>;
      };
      // 실제 프로덕션 코드에서는 Zod로 API 응답 타입을 검증하는 것을 권장합니다
 
      return {
        content: [
          {
            type: "text",
            text: data.items
              .map((item) => `## ${item.title}\n${item.url}\n${item.summary}`)
              .join("\n\n"),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `네트워크 오류: ${error instanceof Error ? error.message : "알 수 없는 오류"}`,
          },
        ],
        isError: true,
      };
    }
  }
);
 
const transport = new StdioServerTransport();
await server.connect(transport);

# 개발 중인 서버를 tsx로 직접 실행하면서 Inspector 연결
npx @modelcontextprotocol/inspector npx tsx src/extended-server.ts

{
  "mcpServers": {
    "company-api": {
      "command": "node",
      "args": ["dist/extended-server.js"],
      "env": {
        "INTERNAL_API_TOKEN": "${INTERNAL_API_TOKEN}",
        "DOCS_API_TOKEN": "${DOCS_API_TOKEN}"
      }
    }
  }
}

{
  "mcpServers": {
    "company-api-dev": {
      "command": "npx",
      "args": ["tsx", "src/extended-server.ts"],
      "env": {
        "INTERNAL_API_TOKEN": "${INTERNAL_API_TOKEN}",
        "DOCS_API_TOKEN": "${DOCS_API_TOKEN}"
      }
    }
  }
}