toy-mcp-server

MCP가 실제로 어떻게 동작하는지 배우기 위해 처음부터 직접 만든 최소한의 Model Context Protocol (MCP) 서버입니다. 보일러플레이트 생성기나 템플릿 없이 SDK만 사용했습니다.

첫 MCP 실습 프로젝트로, 도구 2개와 리소스 1개를 갖추고 stdio로 Claude Desktop에 연결됩니다.

하는 일

MCP는 LLM 클라이언트(예: Claude Desktop)가 학습 데이터에서 텍스트만 생성하는 대신, 로컬 머신에서 실행되는 함수를 호출할 수 있게 합니다. 이 서버는 다음을 제공합니다:

도구(Claude가 호출할 수 있는 함수):

• roll_dice — 면 수를 설정할 수 있는 주사위 N개를 굴립니다.

• flip_coin — 동전을 N번 던집니다.

리소스(Claude가 가져올 수 있는 읽기 전용 데이터):

• server-info — 서버의 기본 메타데이터(이름, 목적, 시작 시간)

존재 이유

LLM은 학습 데이터 밖의 어떤 것에도 접근할 수 없고, 기본적으로는 어떤 것도 하지 못합니다 — 텍스트만 생성할 뿐입니다. MCP는 모델에게 다음을 제공하는 표준적인 방법입니다:

• 능력 — 스스로는 갖지 못한 능력(예: 진짜 무작위성 — LLM은 난수를 스스로 고르는 것을 매우 못하는 것으로 유명합니다)

• 접근 — 모델이 알 수 없는 실시간 또는 비공개 데이터에 대한 접근

이 프로젝트는 MCP 서버를 실제 대상(데이터베이스, 인증이 필요한 API 등)에 연결하기 전에 그 아이디어를 시험해보는 작고 안전한 샌드박스입니다.

기술 스택

• TypeScript

• @modelcontextprotocol/sdk — 공식 MCP SDK

• zod — 도구 인수의 런타임 스키마 검증

• stdio 전송(Claude Desktop과의 로컬 하위 프로세스 통신)

프로젝트 구조

toy-mcp-server/
├── src/
│   └── index.ts       # server setup, tools, and resource
├── build/              # compiled output (git-ignored)
├── package.json
├── tsconfig.json
└── README.md

설정

1. 의존성 설치

npm install

2. 빌드

npm run build

3. Claude Desktop에 연결

Claude Desktop 구성 파일을 찾으세요:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: 보통 %LOCALAPPDATA%\Packages\<Claude package folder>\LocalCache\Roaming\Claude\claude_desktop_config.json 경로에 있습니다. 정확한 경로는 설치 방법(Microsoft Store vs 직접 설치 프로그램)에 따라 다를 수 있습니다. 가장 확실한 방법: Claude Desktop을 열고 Settings → Developer → Local MCP servers → Edit Config로 이동하면, 앱이 실제로 읽는 정확한 파일이 열립니다.

이 서버를 mcpServers 아래에 추가하세요(기존 파일을 덮어쓰지 말고 병합하세요):

{
  "mcpServers": {
    "toy-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/toy-mcp-server/build/index.js"]
    }
  }
}

경로를 사용자 컴퓨터의 build/index.js 실제 절대 경로로 바꾸세요. Windows에서는 JSON 문자열에서 백슬래시(\\)를 이스케이프해야 합니다.

4. Claude Desktop 다시 시작

완전히 종료하고(창을 닫기만 하는 것만으로는 안 됩니다) 다시 실행하세요. toy-mcp-server가 연결된 것으로 표시되는지 Settings → Developer → Local MCP servers에서 확인하세요.

5. 사용해 보기

채팅에서 이렇게 요청해 보세요:

• "6면체 주사위 3개 굴려 줘"

• "동전을 10번 던져 줘"

응답 위에 작은 도구 호출 표시(예: "Roll Dice")가 보일 것입니다. 이는 Claude가 답을 미리 추측한 것이 아니라 실제로 함수를 호출했음을 확인시켜 줍니다.

작동 방식(간단히)

• McpServer — 서버의 기능을 연결하는 어떤 클라이언트에게든 선언하는 객체

• registerTool(name, config, handler) — 호출 가능한 함수를 등록합니다. config.inputSchema는 핸들러가 실행되기 전에 모델이 보낸 인수를 Zod로 검증합니다.

• registerResource(name, uri, config, handler) — URI로 접근할 수 있고 인수 없이 가져오는 읽기 전용 데이터를 등록합니다.

• StdioServerTransport — 통신 규약입니다. Claude Desktop은 이 파일을 하위 프로세스로 실행하고 JSON-RPC로 stdin/stdout을 통해 통신합니다. console.log는 여기서 로깅에 사용하지 않습니다. stdout이 실제 프로토콜 채널이기 때문이며, 대신 console.error(stderr)를 사용합니다.

다음 단계

• 장난감 도구를 실제 데이터베이스(Prisma를 통한 Postgres) 대상 도구로 교체하기

• GitHub 백엔드 도구(예: list_open_prs)를 추가해 토큰 기반 인증 연습

• 로컬에서 실행하는 수고 대신 원격으로 호스팅하기 위해 Streamable HTTP transport 탐구

라이선스

MIT