mCP 서버 설정 및 에이전트 툴 사용법

1. mCP 서버의 기본 개념

mCP 서버는 AI 에이전트(또는 어시스턴트)가 특정 툴을 사용하도록 기능을 노출해주는 서버입니다. 예를 들어 텍스트 분석, API 연동 등 원하는 기능을 자유롭게 만들어 연결해둘 수 있어요. 이렇게 만든 툴을 Claude Desktop과 같은 AI 도구에서 “mCP 서버”로 등록하면, 대화 중 필요한 작업(예: 단어 세기, 번역, 데이터 조회 등)을 에이전트가 바로 호출하여 처리할 수 있습니다.

예시로 “Count R”라는 툴을 mCP 서버 형태로 구현해둔 경우, AI 에이전트가 “Count R 툴로 단어에 포함된 ‘R’ 문자의 개수를 세어봐”라고 요청하면 빠르게 결과를 반환합니다. 내부적으로는 FastMCP 라이브러리를 통해 손쉽게 구축 가능하며, 원하는 기능을 코드로 작성하기만 하면 됩니다.

2. mCP 서버를 시작하는 방법 (기본 절차)

(1) 프로젝트 폴더 및 가상 환경 설정

폴더 생성
원하는 위치에 새 폴더를 만들고 (mkdir count_r_server), 해당 폴더로 이동 (cd count_r_server) 합니다.
가상 환경 생성
python -m venv .venv 명령으로 가상 환경을 만들고, 아래 명령으로 활성화합니다.
- Windows: .venv\Scripts\activate
- macOS/Linux: source .venv/bin/activate

(2) 라이브러리 설치

가상 환경이 활성화된 상태에서 아래 명령으로 mCP 라이브러리를 설치합니다.

pip install mcp

(3) Python 서버 파일 작성

폴더 안에 server.py 파일을 만든 뒤, 아래 예시와 같이 작성합니다.

import time
import signal
import sys
from mcp.server.fast_mcp import FastMCP

def signal_handler(signum, frame):
    print("서버를 종료합니다.")
    sys.exit(0)

signal.signal(signal.SIGINT, signal_handler)

mcp_server = FastMCP(
    name="count_r",
    host="127.0.0.1",
    port=5000,
    timeout=30
)

@mcp_server.tool()
def count(word: str) -> int:
    """
    주어진 단어에서 'R' 문자의 개수를 센다.
    """
    try:
        if not isinstance(word, str):
            return 0
        return word.lower().count('r')
    except Exception as e:
        return 0

if __name__ == "__main__":
    print("mCP 서버를 시작합니다.")
    mcp_server.run()

FastMCP 객체를 통해 서버 세팅을 마치고, @mcp_server.tool()로 AI가 호출할 함수를 정의하면 됩니다.

(4) 서버 실행

python server.py 명령을 입력하면 서버가 실행됩니다. 터미널에 “mCP 서버가 시작되었습니다”라는 메시지가 표시되면 정상 동작 중입니다.

3. 실제 사례 및 경험담 (성공 사례 & 실패 사례)

성공 사례
- Count R 서버 구축: 예시처럼 특정 문자나 단어를 세는 간단한 기능을 mCP 서버로 만들 수 있습니다. Claude Desktop에서 “Strawberry에 포함된 ‘R’은 몇 개인가?” 같은 질문을 빠르게 처리할 수 있죠.
- 날씨 조회 API 연동: 외부 날씨 API를 호출하는 코드를 mCP 형태로 감싸두면, “현재 서울 날씨 어때?” 같은 명령을 Claude가 직접 처리할 수 있습니다.

실패 사례
- 포트 중복 사용: 이미 다른 프로세스가 5000번 포트를 점유 중인데 그대로 서버를 띄워 충돌이 났던 경우. 다른 포트를 사용하거나 기존 프로세스를 종료해야 합니다.
- 설정 미반영: Claude Desktop의 config.json에 mCP 서버 경로를 잘못 기입해서 툴이 인식되지 않았던 사례. 절대 경로 및 JSON 구조를 꼼꼼히 확인해야 합니다.

4. mCP 서버의 장점과 단점 분석

장점

모듈화 & 재활용: 원하는 기능을 서버 형태로 만들어 두면, 여러 AI 프로젝트에서 재활용하기가 쉽습니다.
유연성: Python, Node.js 등 다양한 언어로 원하는 기능을 구현한 뒤 mCP로 감싸, Claude 같은 에이전트에서 호출할 수 있습니다.
확장성: 날씨, 번역, 데이터베이스 조회 등 여러 툴을 추가하면 에이전트가 대화 맥락에 따라 자동으로 필요한 툴을 선택해 씁니다.

단점

초기 설정 복잡: mCP 서버 자체가 낯설면, 설치·설정 과정에서 어려움을 겪을 수 있습니다.
훈련 필요: AI 모델이 툴 사용 방식을 이해하도록 프롬프트 설계나 추가 교육이 필요할 수 있습니다.
별도 프로그램 설치: 현재는 Claude Desktop 버전을 사용해야 하므로, 웹 버전과 연동하기는 아직 번거로운 편입니다.

5. 실질적인 팁과 노하우

포트 충돌 체크: 서버 실행 전 netstat나 lsof -i :포트번호 등으로 포트 사용 여부를 확인하세요.
Reinstall 이슈: Claude Desktop이 mCP 서버를 못 찾으면, Claude Desktop을 재설치하거나 설정을 다시 불러와서 해결해야 할 수 있습니다.
에러 처리: 데이터 타입 불일치, API 실패 등 예외 처리를 코드에 꼼꼼히 넣어두면 안정성이 크게 올라갑니다.
도커 활용: 환경 종속성이 많다면 Docker 컨테이너로 서버를 구성해두면 배포와 유지보수가 편리합니다.

6. mCP 서버를 활용한 장기적인 전략

다양한 툴 확장: 텍스트 처리뿐 아니라 머신러닝 예측, 이미지 처리 등을 mCP 서버로 구현해 두면 AI가 더욱 다양한 작업을 수행할 수 있습니다.
자동화 파이프라인: 일정 시간 간격 또는 특정 이벤트가 발생할 때마다 mCP 서버를 호출해 자동으로 작업을 처리하도록 파이프라인을 구축해보세요.
협업 환경 도입: 팀 내에서 여러 개의 툴 서버를 운영하면, AI가 통합적으로 다양한 기능을 동시에 활용할 수 있습니다.

7. 결론 및 요약

mCP 서버는 AI 어시스턴트(Claude Desktop 등)에서 다양한 외부 기능을 이용할 수 있도록 해주는 훌륭한 방법입니다.
설치와 설정에 조금만 익숙해지면, 단순한 툴부터 고급 기능까지 빠르게 개발해 연결할 수 있죠.
Claude Desktop 설정 파일(config.json)에 mCP 서버 주소를 추가하고, 포트 충돌이나 Reinstall 문제를 신경 써야 하지만, 장기적으로 보면 한 번 설정해 두면 재활용과 확장이 매우 편리합니다.
꼭 작은 툴부터 시작해 보면서, 구축 과정을 직접 체험해보시길 추천드립니다.

#mCP서버 #ClaudeDesktop #AI에이전트 #툴개발 #Python #FastMCP #개발가이드 #인공지능활용

저작자표시 비영리 변경금지 (새창열림)

잡상식