FastMCP로 배우기: AI 에이전트에 자작 도구를 구현하는 최단 경로

현대의 AI 에이전트 개발에 있어, 모델 자체의 성능 향상은 이제 전제 조건입니다. 현재 엔지니어들이 직면한 진정한 과제는 "LLM(대규모 언어 모델)에 어떻게 외부의 전문 지식이나 조작 권한을 안전하고 효율적으로 부여할 것인가"라는 점으로 집약됩니다. 지금까지는 LangChain이나 LlamaIndex 등을 이용하여 개별적으로 도구를 구현해 왔으나, 접속 대상마다 달라지는 구현 비용은 개발의 장벽이 되어 왔습니다.

그 결과 등장한 것이 "Model Context Protocol (MCP)"입니다. MCP는 AI 애플리케이션과 외부 시스템을 연결하기 위한 표준화된 프로토콜입니다. 이번에는 Python으로 MCP 서버를 구축하기 위한 최단 경로인 "FastMCP"에 초점을 맞추어, AI 에이전트에 자작 도구를組み込む 본질적인 의의를 심도 있게 살펴봅니다.

FastMCP는 표준적인 Python의 타입 힌트(Type Hint)와 데코레이터(Decorator)를 활용함으로써, 개발자가 번거로운 프로토콜 정의를 의식하지 않고도 도구를 작성할 수 있는 라이브러리입니다. 왜 이러한 추상화가 중요할까요?

통상적으로 LLM에 도구를 인식시키기 위해서는 함수 이름뿐만 아니라, 인수의 타입이나 역할을 기술한 "JSON 스키마 (JSON Schema)"를 생성하여 모델에 제시해야 합니다. FastMCP의 @mcp.tool 데코레이터는 Python의 함수 정의로부터 이 메타데이터를 자동으로 추출합니다.

다음 코드는 FastMCP를 이용한 기본적인 계산 도구의 구현 예시입니다.

from mcp.server.fastmcp import FastMCP
mcp = FastMCP("MyCalculator")
@mcp.tool()
...

이 코드의 핵심은 docstring(함수의 설명문)이 그대로 LLM에 대한 "추론의 힌트"로서 기능한다는 점에 있습니다. LLM은 프롬프트(Prompt)를 통해 이 함수 이름이나 설명문을 읽어 들여, 언제 그 도구를 호출해야 할지를 판단합니다. 즉, 코드의 가독성이 그대로 AI의 추론 정밀도로 직결된다는 "AI 퍼스트 (AI-first)" 설계가 되어 있는 것입니다.

AI 에이전트가 도구를 선택할 때, LLM은 제공된 메타데이터를 바탕으로 "확률적인 판단"을 수행합니다. 만약 인수의 설명이 모호하다면 모델의 추론은 불안정해집니다. FastMCP를 사용할 때는 단순히 동작하는 코드를 쓰는 것이 아니라, 다음 요소들을 의식해야 합니다.

• 함수명의 명확화: LLM이 직관적으로 이해할 수 있는 명명 규칙을 사용한다.
• 타입 힌트의 엄격화: int나 str을 올바르게 정의하여 유효성 검사(Validation)가 작동하게 한다.
• docstring의 최적화: 도구를 실행할 때의 "목적"이나 "제약"을 자연어로 보충한다.

이를 통해 LLM은 "이 함수를 호출함으로써 목적하는 태스크에 어떻게 기여할 수 있는가"라는 문맥(Context)을 올바르게 이해하고, 오작동을 억제할 수 있습니다.

구축한 FastMCP 서버를 일상적인 워크플로우에서 이용할 수 있도록 합시다. Claude Desktop 앱의 설정 파일(claude_desktop_config.json)을 편집함으로써, 자작 도구를 로컬 AI 환경에 통합할 수 있습니다.

{
"mcpServers": {
"my-calculator": {
...

이 설정을 통해 Claude Desktop이 기동될 때마다 MCP 서버가 백그라운드에서 실행되며, LLM이 직접 만든 계산 도구를 투명하게 이용할 수 있게 됩니다. 이는 단순한 플러그인 추가가 아니라, AI 에이전트가 "외부의 도구를 자율적으로 선택하여 사용하는" 새로운 생태계로의 입구입니다.

MCP라는 표준화된 기반 위에 도구를 구현하는 것은, 향후 모델이 교체되더라도 재사용 가능한 자산을 구축하는 것과 같습니다. 기술의 세부 사항에 신경 쓰면서도, 항상 높은 관점에서 "AI 에이전트와 인간이 어떻게 협업할 것인가"라는 인터페이스 설계를 추구하시기 바랍니다.