이전(④)까지는 공개된 MCP 서버를 클라이언트에 연결하는 '사용하는 쪽'의 이야기였습니다. 이번부터는 '만드는 쪽'으로 돌아갑니다.
본 기사에서는 공식 SDK를 사용하여 툴 하나만 가진 최소 서버를 만들고, 로컬에서 구동하는 과정까지 설명합니다. 코드는 짧고, 구조는 단지 세 가지 부품으로 이루어져 있습니다.
- 최소 MCP 서버가 갖는 3가지 부품
- TypeScript로 최소 서버를 만드는 절차
- Python으로 동일한 것을 작성할 때의 차이점
- 구동 전 확인 방법과 주의하기 쉬운 함정들
MCP 서버는 아무리 커도 다음 세 가지로 구성되어 있습니다.
| 부품 | 역할 |
|---|
| 서버 객체 | 이름과 버전을 가지고, 툴들을 묶습니다. |
| ... | |
| 로컬에서 구동하는 최소 구성에서는 트랜스포트(transport)로 stdio를 사용합니다. 클라이언트가 서버의 프로세스를 시작하고, 표준 입출력(standard input/output)을 통해 JSON-RPC 메시지를 교환하는 방식입니다 (②에서 설명했듯이). | |
TypeScript 공식 SDK는 현재 v2가 안정 버전 계열이며, 패키지명은 @modelcontextprotocol/server이고, 2026-07-28 버전의 MCP 사양에 대응합니다. Node.js는 20 이상을 사용해야 합니다.
mkdir my-first-mcp-server && cd my-first-mcp-server
npm init -y
npm pkg set type=module
...
zod는 툴의 입력 형태를 선언하기 위한 라이브러리입니다. SDK는 이 선언을 기반으로 클라이언트에게 전달할 입력 스키마(JSON Schema)를 자동으로 만듭니다. tsx는 TypeScript를 직접 실행하는 도구로, 빌드 과정이 필요 없습니다. type=module은 SDK가 ES 모듈만으로 제공되기 때문에 필요합니다.
우리가 만들 것은, 전달된 문자열의 글자 수를 세는 count_chars라는 툴 하나만 가진 서버입니다. 파일은 src/index.ts에 위치시킵니다.
import { McpServer } from '@modelcontextprotocol/server';
import { serveStdio } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';
...
포인트는 세 가지입니다.
- 툴 이름 뒤에 「설명」과 「입력 스키마」를 전달합니다. 설명문은 LLM이 「이 툴을 사용해야 하는가」를 판단하는 자료가 되므로,
registerTool의 두 번째 인자에 어떤 역할을 하는 툴인지 구체적으로 작성합니다. -
- 반환값은입니다. 텍스트를 반환할 경우에는
content 배열 { type: 'text', text: '...' } 형태를 사용합니다. -
- 시작은입니다.
serveStdio(createServer)
serveStdio는 클라이언트마다 프로토콜 버전을 협상하기 때문에, 새로운 버전(2026-07-28)의 클라이언트는 물론 오래된 버전의 클라이언트에도 대응할 수 있습니다. server.connect(new StdioServerTransport())와 같이 직접 연결하는 방법도 있지만, 이는 구형 클라이언트에만 대응하므로 현재는 serveStdio를 사용하는 것이 권장됩니다.
실행은 tsx로 바로 진행합니다. 빌드 과정은 필요 없습니다.
아무것도 표시되지 않으면 정상입니다. stdio 서버는 클라이언트로부터의 메시지를 기다리고 있는 상태입니다. 중지할 때는 Ctrl+C를 누릅니다.
Python 공식 SDK(패키지명 mcp, 2.0.0 이상)에서도 동일한 방식으로 작성할 수 있습니다. 이 버전은 타입 힌트와 docstring으로부터 입력 스키마가 자동 생성되는 것이 특징이라, 스키마를 직접 작성할 필요가 없습니다.
from mcp.server import MCPServer
mcp = MCPServer("count-server")
@mcp.tool()
...
TypeScript 버전과의 대응 관계는 다음과 같습니다.
| 역할 | TypeScript | Python |
|---|
| 서버 만들기 | new McpServer({...}) | MCPServer("count-server") |
| 툴 등록하기 | server.registerTool(...) | @mcp.tool() 데코레이터 |
| 입력 형태 결정 | Zod의 inputSchema | |
| 인자 타입 힌트 | | |
| 툴 설명 | description | 함수 docstring |
어떤 것을 선택할지는 팀이 익숙한 언어로 결정해도 무방합니다. 프로토콜은 같기 때문에 TypeScript로 만든 서버를 Python으로 만든 클라이언트에서 호출할 수도 있습니다.
바로 클라이언트에 연결하기 전에, 공식 테스트 도구인 MCP Inspector로 확인하는 것이 좋습니다.
npx @modelcontextprotocol/inspector npx tsx src/index.ts
Inspector가 실행되면 count_chars가 툴 목록에 나타나는지, 실제로 문자열을 전달했을 때 글자 수가 반환되는지 확인합니다. Python의 경우 uv run mcp dev server.py로 동일하게 확인할 수 있습니다.
참고로, Inspector는 기본적으로 구 버전(2025년 기준) 절차로 연결합니다. 새로운 버전(2026-07-28) 클라이언트에 대한 대응까지 확인하고 싶다면, Inspector 실행 시 --protocol-era modern을 붙여서 실행해야 합니다.
작동하는 것이 확인되었다면, ④에서 소개한 방법으로 클라이언트 설정 파일에 서버를 등록합니다. Claude Desktop의 경우 설정 파일의 mcpServers에 시작 명령어(TypeScript라면 node로 빌드된 파일을 지정)를 작성하고 재시작하기만 하면 됩니다.
최소 서버 구축이 실패하는 원인은 대부분 다음 세 가지 중 하나입니다.
stdio 환경에서는 표준 출력이 그대로 프로토콜 통신 경로입니다. console.log를 한 줄이라도 사용하면 JSON-RPC 메시지가 손상되어 서버가 작동하지 않게 됩니다. 로그를 출력하고 싶을 때는 console.error를 사용하세요 (표준 에러 출력은 통신 경로와 분리되어 있습니다). Python에서도 마찬가지로, print()는 사용하지 않습니다.
LLM은 툴의 description을 읽고 사용할지 여부를 결정합니다. “유용한 툴입니다” 같은 설명으로는 호출되지 않거나 잘못 호출될 수 있습니다. “무엇을 받고 무엇을 반환하는지”를 한 문장으로 구체적으로 작성하는 것이 요령입니다.
툴은 하나씩 늘려나가는 것이 기본입니다. 먼저 count_chars와 같이 부작용이 없는 (외부 상태를 변경하지 않는) 툴로, 등록부터 연결까지의 흐름을 통해 작동시켜봅니다. 작동하는 형태가 만들어진 후에 파일 조작이나 외부 API 호출과 같은 실용적인 툴을 추가해 나갑시다.
- 최소 MCP 서버는 “서버 객체”, “툴 등록”, “전송 계층 연결”의 세 부분만으로 구성됩니다.
- TypeScript는
@modelcontextprotocol/server의 McpServer와 registerTool, 시작은 serveStdio를 사용하고, 입력 스키마에는 Zod를 사용합니다. - Python은 mcp 패키지의 MCPServer와 @mcp.tool()을 사용하며, 타입 힌트와 docstring이 스키마가 됩니다. - stdio 환경에서는 표준 출력에 아무것도 쓰지 않습니다 (로그는 표준 에러 출력으로 보냅니다).
- 작동시키기 전에 MCP Inspector로 툴 목록과 호출 여부를 확인합니다.
다음 편(⑥)에서는 툴 구현을 한 단계 더 진행하여, 스키마 정의, 인자 유효성 검사(validation), 에러 처리 등 구현에서 막히기 쉬운 점들을 설명하겠습니다.
-
MCP 서버에 관하여 ④: 사용하는 쪽부터 시작하기: 기존 서버 도입 및 연결
-
MCP 서버에 관하여 ③: 서버가 제공하는 세 가지 기능
-
MCP 서버에 관하여 ②: 통신 메커니즘
-
MCP 서버에 관하여 ①: 전체 개요와 기본 개념
-
MCP(Model Context Protocol): LLM 애플리케이션과 외부 데이터 및 도구를 공통의 규칙으로 연결하기 위한 프로토콜(통신 규약)입니다.
-
SDK(Software Development Kit): 특정 기술을 사용하기 위한 공식 라이브러리 및 도구 모음입니다. 여기서는 MCP 서버를 만드는 데 필요한 공식 라이브러리입니다.
-
stdio: 표준 입출력(standard input / output)의 약어입니다. 프로세스들이 키보드 입력이나 화면 출력과 동일한 방식으로 메시지를 주고받는 방식입니다.
-
트랜스포트(Transport): 클라이언트와 서버 사이에서 메시지를 전달하는 경로입니다. stdio와 Streamable HTTP가 있습니다.
-
JSON-RPC: JSON 형식으로 '메서드 이름'과 '인수(argument)'를 보내고, '결과(result)'를 받는 원격 호출 메커니즘입니다. MCP 메시지 교환의 기반이 됩니다.
-
Zod: TypeScript에서 데이터의 형태(스키마, schema)를 선언하고 검증하기 위한 라이브러리입니다.
-
MCP Inspector: MCP 서버의 동작을 테스트하기 위한 공식 도구입니다. 도구 목록 표시 및 호출이 가능합니다.
-
데코레이터(Decorator): Python에서 함수나 클래스 정의 위에 붙여 그 동작을 확장하는 문법입니다. 예시: @mcp.tool()
은(는) 함수를 MCP 도구로 등록합니다.
-
타입 힌트(Type Hinting): Python에서 인자나 반환값의 타입을 주석으로 작성하는 것입니다. SDK는 이를 통해 입력 스키마를 만듭니다.
-
docstring: Python 함수나 클래스 내부에 작성하는 설명문입니다. SDK는 이를 통해 도구의 설명을 만듭니다.
-
부작용(Side Effect): 프로그램 실행으로 인해 파일이나 데이터베이스 등 외부 상태가 변경되는 것을 말합니다. 읽기 전용 처리에는 부작용이 없습니다.