연재: AI에게 일자리를 빼앗길 불안에서 시작하는 하네스 작성 입문 제8회 MCP 서버 최소 구현 — FastMCP로 첫 번째 툴 만들기

연재: AI에게 일자리를 빼앗길 불안에서 시작하는 하네스 작성 입문

전 24회 (주 2회 · 12주간) | 제8회 / 24

이 연재는 AI에게 일자리를 빼앗길지도 모른다는 불안을 '하네스(Harness, AI 에이전트 제어 메커니즘)'를 직접 만드는 행동으로 바꾸는 시리즈입니다.

"MCP 서버를 만들어 보고 싶지만, 무엇부터 써야 할지 모르겠다" —— 지난 회차(제7회)에서 MCP 서버의 분할 설계(Split Design)를 수행하고, MCP 책임 표(MCP Responsibility Table)까지 만들었습니다. 하지만 설계도가 있어도 '첫 번째 한 줄'을 쓰지 못하면 손이 멈추게 됩니다.

이번에는 그 불안을 해소하기 위해 FastMCP를 사용한 최소 구현을 체험합니다. "생각보다 적은 코드로 동작한다"는 감각을 잡는 것이 목표입니다.

• SE·프로그래머 경험 3년 이상인 분
• Python의 기본 구문(함수, 데코레이터(Decorator), 타입 힌트(Type Hint))을 이해하고 있는 분
• MCP 서버를 실제로 만들고 싶은 분
• 지난 연재를 읽어온 분 (읽지 않았어도 OK)

MCP 서버의 최소 구현은 Python 함수에 데코레이터를 붙이는 것뿐입니다. @mcp.tool()을 붙인 함수가 그대로 AI 에이전트로부터 호출할 수 있는 툴(Tool)이 됩니다. SE 경험자가 API 설계에서 쌓은 "인수의 타입을 결정하기", "반환값의 형식을 통일하기" 스킬이 그대로 활용됩니다.

제7회에서 만든 MCP 책임 표에는 4개의 MCP 서버가 있었습니다. 전부 한꺼번에 만들려고 하면 다음과 같은 문제가 발생합니다.

설계의 망설임: 처음부터 완벽한 인터페이스를 설계하려다 보니 손이 멈춤 -
동작 확인의 지연: 코드가 늘어날수록 첫 동작 확인까지 걸리는 시간이 길어짐 -
동기 부여 저하: 성과가 보이지 않는 채로 설계만 진행됨

SE라면 "먼저 프로토타입(Prototype)을 만들어 동작시켜 본 뒤 개선한다"는 접근 방식에 익숙할 것입니다. MCP 서버도 마찬가지입니다. 먼저 1개의 MCP 서버에 2개의 툴을 구현하여 동작시키는 것부터 시작합시다.

SE 경험	MCP 서버 구현에 대한 활용
API 설계 (RESTful)	툴의 인수·반환값 설계
...

FastMCP는 MCP 서버를 Python으로 간편하게 구축하기 위한 프레임워크입니다. 최소 5줄이면 MCP 서버가 동작합니다.

from mcp.server.fastmcp import FastMCP
mcp = FastMCP("my-first-mcp")
@mcp.tool()
...

이것만으로 AI 에이전트로부터 hello 툴을 호출할 수 있는 MCP 서버가 완성됩니다.

FastMCP("서버 이름")로 서버 인스턴스를 생성 -
@mcp.tool() 데코레이터로 함수를 툴로 등록 -
mcp.run()으로 stdio(표준 입출력) 트랜스포트(Transport)로 기동 HTTP 서버를 직접 구축할 필요가 없음

제7회에서 설계한 article_mcp(기사 작성·관리)의 첫 번째 툴을 구현합니다.

import os
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("article-mcp")
...

MCP 툴의 시그니처(Signature, 인수와 반환값)는 AI 에이전트와의 **계약(Contract)**입니다. SE 관점에서는 API의 인터페이스 정의와 같습니다.

설계 요소	역할	SE적 대응
함수명	AI가 툴을 선택하는 단서	API 엔드포인트(Endpoint) 이름
...

반환값은 항상 dict로 통일한다: {"ok": True/False, ...} 형식으로 만들면 성공/실패 판정을 AI와 프로그램 모두 용이하게 처리 가능 -
예외(Exception)를 던지지 않고 dict로 에러를 반환한다: MCP에서는 JSON-RPC 사양상, Python 예외보다 dict 기반의 에러 응답이 안전함 -
docstring은 반드시 작성한다: AI 에이전트는 docstring을 읽고 툴을 선택한다. 비어 있으면 호출되지 않을 가능성이 있음

# 가상 환경 활성화
python -m venv .venv
.venv\Scripts\activate # Windows
...

AI 개발 환경(Antigravity, Claude Desktop 등)에 MCP 서버를 등록하려면 설정 파일에 서버 정보를 추가합니다.

{
"mcpServers": {
"article-mcp": {
...

등록 후, AI 에이전트에게 "health_check를 호출해줘"라고 지시하면 서버의 상태가 반환됩니다. 직접 작성한 Python 함수가 AI에 의해 호출되는 것——이 경험이 하네스 (Harness) 개발의 첫걸음입니다.

주의사항	이유	대책
첫 번째 툴은 2~3개로 제한한다	툴이 너무 많으면 AI가 혼란을 겪는다	health_check + 업무용 툴 1~2개
...

FastMCP로
health_check

툴을 가진 MCP 서버 만들기 - 또 다른, 자신의 용도에 맞는 업무용 툴을 추가한다

• 로컬에서 stdio 모드 실행을 확인한다
• AI 개발 환경에 접속하여 툴이 호출되는 것을 확인한다
• (발전) 제7회의 MCP 책임 표에 있는 다른 MCP 서버들도 최소 구현해 본다

이번에는 FastMCP를 사용한 MCP 서버의 최소 구현을 체험했습니다.

키포인트 (Key Points)

• MCP 서버 구현은 "함수 + 데코레이터 (Decorator)"만으로 시작할 수 있다
• 툴의 시그니처 (Signature) 설계는 SE 경험의 API 설계 기술을 그대로 사용할 수 있다
• 반환값은 dict로 통일하고, 에러도 dict로 반환한다
• docstring과 타입 힌트 (Type Hint)가 AI 에이전트와의 "계약"이 된다
• 우선 2~3개의 툴로 구동하며 점진적으로 키워나가는 접근 방식이 현실적이다

**제9회 「RAG / Knowledge MCP가 SE 경험자에게 적합한 이유」**에서는 지식 기반 (Knowledge Base)의 세계로 깊이 들어갑니다.

• RAG (Retrieval-Augmented Generation)의 기본 개념

• Knowledge MCP가 하네스에서 수행하는 역할

• SE 경험자가 "DB 설계" 지식으로 RAG를 이해할 수 있는 이유

• 지식 관리 방침 (무엇을, 어떻게 등록하고, 어떻게 검색할 것인가)

• 이번에 만든 MCP 서버를 보관해 둔다 (다음 회차에서 knowledge_mcp를 추가할 때 참고합니다)

• "문서를 검색하는" 경험을 되돌아본다 (사내 Wiki, Confluence, Notion 등)

• "그 정보가 어디 있었더라"라며 곤란했던 경험을 메모해 둔다

회차	제목	상태
제1회	"AI에게 일을 빼앗긴다"는 불안의 정체를 분해한다	✅
...
연재: AI에게 일을 빼앗길 불안에서 시작하는 하네스 작성 입문

저자: @and-and-and ｜ 주 2회 업데이트

다음 회차는 「RAG / Knowledge MCP가 SE 경험자에게 적합한 이유」를 예정하고 있습니다.