claudekit / guides / build-mcp-server
[ Guide · Advanced · 25분 ]

MCP 서버 직접 만들기

published · updated

MCP 서버를 직접 만들어 Claude를 외부 서비스에 연결하는 방법을 다룹니다. 트랜스포트 선택, OAuth 처리, Claude Code에 연결하는 절차를 정리합니다.

MCP란?

Model Context Protocol(MCP)은 Claude가 외부 서비스에 안전하고 표준화된 방식으로 접근할 수 있게 해주는 프로토콜입니다. 한 번 만든 MCP 서버는 Claude Code, Claude Desktop, MCP를 지원하는 다른 IDE에서 그대로 사용할 수 있습니다.

트랜스포트 선택

트랜스포트적합한 경우인증
HTTP (Streamable HTTP)원격 호스팅 SaaS, 다중 사용자OAuth, API 키
stdio로컬 CLI 도구, 시스템 접근환경변수, 토큰
SSEdeprecated, 일부 레거시 원격 서버OAuth

최신 MCP 명세(2026-07-28)가 정의하는 표준 트랜스포트는 stdio와 Streamable HTTP 두 가지입니다. 신규 원격 서버는 HTTP를 선택합니다. Claude Code v2.1.265 이상은 --transport http로 추가한 서버가 HTTP를 받지 않으면 SSE로 자동 전환합니다.

시작 준비

필요한 것:

  • Node.js 20 이상 (TypeScript SDK v2 기준) 또는 Python 3.11 이상 (Python SDK v2 기준)
  • Claude Code 설치 완료
  • 연결하고 싶은 서비스나 데이터 소스

프로젝트 초기화 (TypeScript 예시)

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/server zod tsx
mkdir src

SDK는 ES 모듈로만 배포되므로 type=module 설정이 필요합니다. tsx가 TypeScript를 바로 실행하므로 별도 빌드 단계가 없습니다.

TypeScript SDK v2는 2026-07-27에 stable로 출시됐고 2026-07-28 MCP 명세를 구현합니다. 이전 패키지인 v1(@modelcontextprotocol/sdk)도 계속 동작하지만, v1.x 브랜치에서 버그와 보안 수정만 받습니다(v2 출시 후 최소 6개월).

기본 구조

MCP 서버는 세 가지 요소로 구성됩니다.

  1. Tools — Claude가 호출할 수 있는 함수
  2. Resources — Claude가 읽을 수 있는 데이터 (파일, DB 행 등)
  3. Prompts — 미리 정의된 프롬프트 템플릿

대부분의 서버는 Tools만 있어도 충분합니다.

Tool 정의 (예: 날씨 조회)

src/index.ts:

import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";

function createServer(): McpServer {
  const server = new McpServer({ name: "weather-server", version: "1.0.0" });

  server.registerTool(
    "get-weather",
    {
      description: "Returns current weather for a city",
      inputSchema: z.object({
        city: z.string().describe("City name in English"),
      }),
    },
    async ({ city }) => {
      const weather = await fetchWeather(city); // 날씨 API 호출 (직접 구현)
      return {
        content: [{ type: "text", text: JSON.stringify(weather, null, 2) }],
      };
    }
  );

  return server;
}

inputSchema에는 Zod 스키마(z.object(...))를 넘깁니다. SDK가 이 스키마로 모델에 보여줄 JSON Schema를 만들고, 핸들러가 실행되기 전에 인자를 검증합니다.

도구 설명(description)은 Claude가 도구를 언제 호출할지 결정하는 핵심 정보입니다. 명확하고 구체적으로 작성합니다.

stdio 트랜스포트로 실행

파일 끝에 다음을 추가합니다.

void serveStdio(createServer);
console.error("weather MCP server running on stdio");

실행:

npx tsx src/index.ts

stdio에서는 stdout이 프로토콜 채널입니다. 로그는 console.error로 stderr에 출력합니다. console.log를 한 번만 써도 JSON-RPC 스트림이 깨집니다.

Claude Code는 stdio 서버를 실행할 때 프로젝트 루트를 CLAUDE_PROJECT_DIR 환경변수로 넘깁니다. 프로젝트 기준 상대 경로가 필요하면 process.env.CLAUDE_PROJECT_DIR를 읽습니다.

호스트 없이 도구를 직접 호출해 보려면 MCP Inspector를 사용합니다.

npx @modelcontextprotocol/inspector npx tsx src/index.ts

Python으로 만들기

Python SDK v2는 MCPServer와 데코레이터로 도구를 정의합니다. 타입 힌트가 곧 입력 스키마가 됩니다.

uv add "mcp[cli]"      # 또는: pip install "mcp[cli]"
from mcp.server import MCPServer

mcp = MCPServer("weather-server")


@mcp.tool()
def get_weather(city: str) -> str:
    """Returns current weather for a city."""
    return fetch_weather(city)  # 날씨 API 호출 (직접 구현)


if __name__ == "__main__":
    mcp.run()  # 인자 없이 호출하면 stdio 서버로 실행

Claude Code에는 다음처럼 연결합니다. uv run --with가 실행할 때마다 SDK 환경을 준비하므로 어느 디렉터리에서 실행돼도 동작합니다.

claude mcp add weather-py -- uv run --with "mcp[cli]" mcp run /absolute/path/to/server.py

Claude Code에 연결

1. 로컬 stdio 서버 추가

프로젝트 루트에서 실행합니다. -- 뒤가 서버 실행 명령입니다.

claude mcp add weather -- npx tsx src/index.ts

기본 범위는 local(현재 프로젝트에서 나만 사용)입니다. --scope user를 붙이면 모든 프로젝트에서, --scope project를 붙이면 .mcp.json을 통해 팀 전체와 공유할 수 있습니다. 다른 디렉터리에서도 실행되는 user 범위라면 서버 파일 경로를 절대 경로로 적습니다.

2. 원격 HTTP 서버 추가

claude mcp add --transport http weather https://mcp.example.com/mcp

OAuth가 필요한 경우 /mcp 명령으로 인증 링크를 받습니다.

3. 프로젝트 단위 공유 (.mcp.json)

.mcp.json을 프로젝트 루트에 두면 팀원이 동일한 MCP 설정을 공유할 수 있습니다.

{
  "mcpServers": {
    "weather": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

서버가 요청 없이도 이벤트를 보내야 한다면 .mcp.json에 "type": "ws"(WebSocket)도 지정할 수 있습니다. 다만 WebSocket은 헤더 인증만 지원하고 OAuth와 claude mcp add --transport 플래그는 지원하지 않습니다.

Claude Desktop에 연결

Claude Desktop은 자체 설정 파일로 stdio MCP 서버를 로드합니다. Claude Code의 claude mcp add가 아니라 직접 JSON 파일을 편집해야 합니다.

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

파일이 없으면 새로 만듭니다. Desktop은 프로젝트 디렉터리 밖에서 서버를 실행하므로 경로는 절대 경로로 적습니다.

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/my-mcp-server/src/index.ts"]
    }
  }
}

호스트는 최소한의 PATH로 서버를 실행하므로 npx나 uv를 찾지 못할 수 있습니다. 이 경우 which npx(Windows는 where npx)로 확인한 절대 경로를 command에 넣습니다. Python 서버는 uv run mcp install server.py를 실행하면 SDK가 Desktop 설정 파일에 항목을 직접 추가합니다.

저장한 후 Desktop 앱을 완전히 종료(Cmd+Q) 하고 다시 실행해야 적용됩니다. 창을 닫는 것만으로는 프로세스가 종료되지 않습니다. 다시 실행한 뒤 채팅 입력창 아래 도구 패널에서 노출된 도구 목록을 확인할 수 있습니다.

권한 민감한 도구 디자인

셸 실행, 파일 시스템, 외부 네트워크처럼 권한이 강한 작업을 노출할 때는 도구를 좁게 쪼개는 것이 핵심입니다. Claude Code의 권한 규칙은 mcp__<server>__<tool>처럼 도구 이름 단위로 지정하며, settings 파일에서는 MCP 도구의 인자 값으로 규칙을 걸 수 없습니다. 한 도구의 입력 스키마가 넓을수록 그 도구를 한 번 허용했을 때의 위험이 커집니다.

나쁜 예 — 범용 셸 노출

server.registerTool("run_shell", {
  description: "Runs an arbitrary shell command",
  inputSchema: z.object({ command: z.string() }),
}, async ({ command }) => { /* ... */ });

이 한 도구는 ls부터 rm -rf, curl까지 모든 작업을 같은 권한 단위로 묶습니다. 이 도구를 한 번 허용하면 사실상 무제한 셸 접근이 됩니다.

좋은 예 — 의도별 분리

server.registerTool("list_files", {
  description: "Lists files in a directory",
  inputSchema: z.object({ path: z.string() }),
}, /* ... */);

server.registerTool("read_file", {
  description: "Reads a text file",
  inputSchema: z.object({ path: z.string() }),
}, /* ... */);

server.registerTool("git_status", {
  description: "Returns git status for the current repo",
  inputSchema: z.object({}),
}, /* ... */);

각 도구가 좁은 입력 스키마를 가지므로 의도하지 않은 작업이 끼어들 여지가 줄고, 사용자가 도구별로 다른 허용 정책을 세울 수 있습니다.

설계 원칙

  • 프롬프트가 아니라 스키마로 제약 — description에 “위험한 명령 금지”를 적기보다 inputSchema에서 허용 범위를 좁힘
  • 부수효과가 있는 도구(쓰기, 실행)와 읽기 전용 도구를 이름과 반환값으로 명확히 구분
  • 경로와 URL 인자는 서버 측에서 화이트리스트로 한 번 더 검증 — Claude가 전달하는 값을 신뢰하지 않음

테스트

claude
/mcp

추가한 서버 상태와 노출된 도구 목록이 보입니다. 그 후 일반 대화로 도구를 호출하도록 요청해 동작을 확인합니다.

배포 패턴

  • SaaS 서비스 — 자체 도메인에 HTTP MCP 서버 배포 (예: https://mcp.notion.com/mcp). 사용자가 OAuth로 인증.
  • 개인용 도구 — npm 패키지로 배포하고 README에 claude mcp add 명령 제공.
  • 플러그인으로 묶기 — MCP 서버를 플러그인에 포함해 마켓플레이스로 배포하면 사용자가 플러그인 설치만으로 서버를 함께 받습니다.

다음 단계

§ 15

자주 묻는 질문

자주 묻는 질문
§ 15.1
MCP 서버는 무엇인가요?
Claude가 외부 서비스(DB, API, SaaS)에 표준화된 방식으로 접근할 수 있게 해주는 서버입니다. Tools(함수), Resources(데이터), Prompts(템플릿)를 정의하면 Claude가 호출할 수 있습니다.
§ 15.2
어떤 트랜스포트를 선택해야 하나요?
원격 서비스라면 HTTP(Streamable HTTP), 로컬 도구라면 stdio가 일반적입니다. 원격 호스팅 가능하고 다중 사용자가 사용할 거면 HTTP, 개인 환경에서만 쓰는 도구나 시스템 권한이 필요한 경우에는 stdio가 적합합니다. SSE는 deprecated 상태입니다.
§ 15.3
Claude Code에 어떻게 연결하나요?
원격 HTTP 서버는 `claude mcp add --transport http <name> <url>`, 로컬 stdio 서버는 `claude mcp add <name> -- <command>`로 추가합니다. 프로젝트 단위 공유는 `.mcp.json`에 정의합니다.
§ 15.4
Claude Desktop에서도 같은 서버를 쓸 수 있나요?
stdio MCP 서버라면 macOS는 `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows는 `%APPDATA%\Claude\claude_desktop_config.json`에 동일한 `mcpServers` 블록을 추가하면 됩니다. 저장 후 Desktop 앱을 완전히 종료하고 다시 실행해야 적용됩니다.
§ 15.5
OAuth 인증은 어떻게 처리하나요?
MCP 명세는 MCP 서버가 OAuth 2.0 Protected Resource Metadata(RFC 9728, `/.well-known/oauth-protected-resource`)를 구현하도록 요구하며, 클라이언트는 이 메타데이터로 인가 서버를 찾습니다. Claude Code에서는 `/mcp` 명령으로 인증 링크를 받아 브라우저에서 로그인합니다.
§ 15.6
기존 도구를 MCP로 만들어 배포하면 무엇이 좋은가요?
Claude Code, Claude Desktop, 그리고 MCP를 지원하는 다른 IDE에서 같은 도구를 그대로 쓸 수 있습니다. 도구별로 IDE 통합을 따로 만들 필요가 없어 배포와 유지보수 비용이 줄어듭니다.