Claude와 Python을 사용하여 나의 첫 번째 MCP 서버 구축하기

며칠 전, 저는 MCP (Model Context Protocol)를 탐구하기 시작했고 AI 도구들이 실제로 외부 시스템과 어떻게 상호작용하는지 이해하고 싶었습니다. 단순히 문서를 읽는 대신, 저는 간단하고 실질적인 프로젝트를 직접 만들어 보기로 했습니다:

Claude가 Dev.to 플랫폼에 블로그 게시물을 직접 게시할 수 있도록 하는 커스텀 MCP 서버.

이 프로젝트를 통해 저는 MCP 서버, AI 도구 호출 (Tool Calling), Claude 통합, 에이전트 워크플로우 (Agent Workflows), 그리고 구조화된 AI 자동화 (Structured AI Automation)를 이해할 수 있었습니다. 이 포스트에서는 제가 무엇을 만들었는지, 어떻게 작동하는지, 그리고 그 과정에서 무엇을 배웠는지 공유하겠습니다.

MCP란 무엇인가?

**MCP (Model Context Protocol)**는 Claude와 같은 AI 모델이 외부 도구 및 시스템과 안전하게 상호작용할 수 있도록 해주는 프로토콜입니다.

쉽게 말해, MCP는 AI에게 단순히 질문에 답하는 것을 넘어 무언가를 수행할 수 있는 능력을 부여합니다. MCP를 통해 AI는 다음과 같은 일을 할 수 있습니다:

• 파일 읽기 및 생성
• 외부 API 호출
• 콘텐츠 게시
• 데이터베이스 접근
• 애플리케이션과 상호작용

이는 AI 에이전트 (AI Agents)와 에이전트 워크플로우 (Agentic Workflows)를 뒷받침하는 핵심 기반 중 하나입니다.

내가 만든 것

저는 다음을 사용하여 간단한 MCP 서버를 제작했습니다:

• Python — MCP 도구 구축용
• Claude Desktop — AI 인터페이스 역할
• Dev.to API — 블로그 게시물 게시용

엔드 투 엔드 (End-to-end) 워크플로우는 다음과 같았습니다:

텍스트 파일 → Claude 정교화 → 마크다운 (Markdown) 생성 → Dev.to 게시

프로젝트 흐름

시스템이 단계별로 어떻게 작동했는지 설명하겠습니다.

1단계 — Claude Desktop 설정

저는 Claude Desktop 설정 파일을 수정하여 제가 만든 커스텀 MCP 서버를 연결했습니다. Claude Desktop을 재시작한 후, Claude 내부에서 커스텀 도구를 사용할 수 있게 되었습니다.

이 순간 MCP 도구가 AI 시스템과 어떻게 직접 통합되는지 확인하며 모든 것이 이해되기 시작했습니다.

2단계 — MCP 도구 생성

Python을 사용하여 다음과 같은 기능을 수행하는 도구들을 만들었습니다:

• 파일에서 블로그 콘텐츠 읽기
• 마크다운 (Markdown) 출력 생성
• API를 통해 Dev.to에 블로그 게시

기본적인 구조는 다음과 같았습니다:

@app.tool()
def publish_blog():
    pass

이것은 해당 함수를 Claude가 발견하고 호출할 수 있는 도구 (Tool)로 등록합니다.

Step 3 — 가공되지 않은 블로그 콘텐츠 제공

저는 다듬어지지 않은 블로그 콘텐츠가 담긴 일반 텍스트 파일을 생성한 후, Claude에게 다음을 요청했습니다:

1. 콘텐츠를 다듬을 것 (Refine)
2. 적절한 마크다운 (Markdown) 형식으로 변환할 것

Claude는 게시 준비가 완료된 세련된 마크다운 파일을 성공적으로 생성했습니다.

Step 4 — Dev.to에 게시하기

마지막으로, 저는 Claude에게 MCP 도구를 사용하여 마크다운 파일을 Dev.to에 게시하도록 요청했습니다. 워크플로우는 다음과 같습니다:

1. 마크다운 파일 읽기
2. Dev.to API 호출
3. 기사 자동 게시

제가 직접 구축한 도구를 통해 AI 시스템이 외부 API와 상호작용하는 것을 보는 것은 진심으로 흥미로운 경험이었습니다.

배운 점

이 프로젝트는 단순한 API 통합 그 이상의 많은 것을 가르쳐 주었습니다.

1. AI 도구에는 구조화된 출력 (Structured Outputs)이 필요합니다

AI 시스템은 예측 가능하고 구조화된 응답을 받을 때 훨씬 더 잘 작동합니다. 단순히 "Success"와 같은 일반 문자열을 반환하는 대신, 다음과 같이 반환하는 것이 훨씬 좋습니다:

{
  "success": true,
  "message": "Blog published successfully"
...

구조화된 출력은 AI 에이전트가 도구를 더 쉽게 파싱하고 신뢰할 수 있게 동작하도록 만듭니다.

2. 에러 핸들링 (Error Handling)은 매우 중요합니다

AI 에이전트는 예상치 못한 방식으로 실패할 수 있으므로, 도구는 잘못된 입력, API 실패, 파일 누락, 네트워크 오류를 포함한 예외 상황(Edge cases)을 유연하게 처리해야 합니다. 견고한 에러 핸들링이야말로 단순한 장난감과 신뢰할 수 있는 시스템을 구분 짓는 요소입니다.

3. MCP는 API를 바라보는 관점을 재정의합니다

전통적인 API는 프론트엔드 앱과 인간 사용자를 위해 설계되었습니다. 반면, MCP 도구는 AI 시스템을 위해 설계되었습니다. 이러한 변화는 명확한 설명, 구조화된 스키마 (Schema), 예측 가능한 출력, 그리고 기계가 읽을 수 있는 에러가 매우 중요해짐을 의미합니다.

4. AI + 도구의 결합은 근본적으로 다르게 느껴집니다

이 프로젝트는 저에게 _챗봇 (chatbot)_과 AI 에이전트 (AI agent) 사이의 차이점을 실질적으로 체감하게 해주었습니다. 질문에 답하는 챗봇은 하나의 단계일 뿐입니다. 파일을 읽고, 콘텐츠를 다듬고, 마크다운 (markdown)을 생성하며, 자율적으로 블로그를 게시하는 AI는 완전히 다른 차원의 존재이며, 훨씬 더 강력합니다.

내가 직면했던 도전 과제들

어떤 프로젝트든 완벽할 수는 없습니다. 제가 겪었던 몇 가지 문제들은 다음과 같습니다:

• 패키지 설치 충돌 (Package installation conflicts)
• uv 환경 설정
• Claude Desktop 설정 오류
• MCP 도구 감지 문제
• API 디버깅 (API debugging)

이 각각의 문제들을 해결하는 과정은 단순히 튜토리얼을 따라가는 것보다 훨씬 더 깊은 수준에서 생태계를 이해하는 데 도움이 되었습니다.

사용된 기술

도구	용도
Python	MCP 도구 구축
...

마치며

이 MCP 서버를 구축하면서 AI 시스템에 대한 저의 사고방식이 완전히 바뀌었습니다. 우리는 단순히 응답하는 (responds) AI에서, 도구를 사용하여 읽고, 쓰고, 생성하고, 자율적으로 게시할 수 있는, 즉 행동할 수 있는 (act) AI 시스템으로 나아가고 있습니다.

비록 작은 프로젝트였지만, AI 툴링 (tooling)의 미래에 대한 강력하고 실질적인 입문 기회가 되었습니다. 만약 AI 에이전트와 에이전트 워크플로우 (agentic workflows)에 대해 궁금하다면, 직접 이와 같은 것을 만들어 보시기를 강력히 추천합니다. 이를 이해하는 가장 좋은 방법은 직접 만들어 보는 것입니다.

질문이 있거나 여러분만의 MCP 실험 내용을 공유하고 싶으신가요? 아래에 댓글을 남겨주세요!