내 API를 클로드 도구로 감싸는 법

챗봇에게 「우리 고객 좀 찾아줘」라고 말하면 실제 사내 시스템을 뒤져 답하게 하려면, 모델에 API 열쇠를 그대로 쥐여줘야 할까. 답은 아니오다. 개발 매체 데브클럽하우스(devclubhouse)가 공개한 실습은 자격증명을 모델에 단 한 번도 노출하지 않고, 사내 REST API를 LLM이 쓸 수 있는 「도구」로 감싸는 법을 보여준다.

무슨 일인가

핵심 기술은 모델 컨텍스트 프로토콜(MCP)과 파이썬 라이브러리 패스트MCP(FastMCP)다. 실습은 사내 API를 세 개의 타입 지정 도구 — 고객 검색·주문 조회·지원 티켓 생성 — 로 감싼다. 이렇게 만든 서버는 클로드 데스크톱(Claude Desktop)·커서(Cursor)·자체 에이전트 등 MCP를 지원하는 어떤 클라이언트든 그대로 호출할 수 있다. 모델은 원시 URL을 조립하거나 인증 키를 볼 일이 전혀 없다.

핵심 짚어보기

서버 코드는 짧다. FastMCP 객체를 만들고 함수에 @mcp.tool() 장식을 붙이면 그 함수가 곧 도구가 된다. 비결은 파이썬의 타입 표기다. 함수 인자에 적은 타입에서 JSON 스키마가 자동 생성돼, 모델이 정확한 입력 형식을 넘겨받는다. 함수 설명문(docstring)은 모델이 호출 전 읽는 도구 설명이 되므로 API 명세처럼 써야 한다. 오류 처리도 영리하다. 응답 상태 검사(raise_for_status)나 값 검증(ValueError)에서 던진 예외가 모델에는 「구조화된 도구 오류」로 전달돼 서버가 죽지 않는다. 인증 키는 환경 변수에 담아 도구 인자로도, 응답으로도, 소스 코드로도 새지 않게 한다. 코드를 짠 뒤에는 mcp dev server.py로 검사 도구(Inspector)를 띄워, LLM에 연결하기 전에 브라우저에서 도구가 제대로 도는지 먼저 확인한다.

1인기업 실전 적용 포인트

• 내 서비스에 AI 손잡이 달기: 고객 DB·주문 시스템·재고 API를 도구 몇 개로 감싸면, 클로드에게 「3번 주문 상태 확인해줘」를 자연어로 시킬 수 있다.
• 키 노출 차단: API 키는 환경 변수(.env)에 두고 .gitignore에 즉시 추가해, 모델도 깃 저장소도 키를 보지 못하게 한다.
• 타입으로 스키마 자동화: 별도 명세를 쓰지 말고 함수 인자 타입과 설명문만 정성껏 적어, 모델이 도구를 헷갈리지 않게 한다.
• 연결 전 검증: mcp dev의 검사 도구로 입력 폼을 띄워 먼저 손으로 호출해 보고, 정상 확인 후에야 클로드 데스크톱 설정에 절대 경로로 등록한다.

전망 / 주의점

필요 환경은 파이썬 3.10 이상과, 검사 도구 실행에 쓰이는 노드(Node.js) 18 이상이다. 통신은 표준 입출력(stdio) 방식이 기본이라 클라이언트가 서버를 하위 프로세스로 띄워 주고받는데, 클로드 데스크톱은 가상환경을 자동 활성화하지 않으므로 설정에 반드시 절대 경로를 넣어야 한다. 한 번 익혀두면 사내 어떤 API든 같은 패턴으로 AI에 물릴 수 있어, 1인기업이 자기 도구를 에이전트화하는 가장 빠른 길이 된다.

출처: 데브클럽하우스 (https://www.devclubhouse.com/a/ship-an-mcp-server-in-python-that-exposes-your-internal-api-to-llms)