CLOVA Studio 운영자5 Posted November 20 공유하기 Posted November 20 들어가며 실제 서비스 운영 단계에서 MCP 서버를 안정적으로 관리하고, 다양한 환경에서 효율적으로 확장할 수 있는 방법을 이해하는 것이 중요합니다. 또한 CLOVA Studio 모델을 기반으로 손쉽게 MCP 연동 프로토타입을 구현하는 방법도 함께 익혀두면 좋습니다. 마지막 4부에서는 MCP Inspector를 활용한 서버 디버깅, Flowise를 통한 시각적 운영 및 테스트, 그리고 MCP 서버를 작성하는 가이드를 다룹니다. 이러한 실전 팁을 통해 HyperCLOVA X와 MCP를 함께 활용해 더 유연하고 효율적인 서비스 환경을 구축해 볼 수 있습니다. MCP 실전 쿡북 4부작 시리즈 ✔︎ (1부) LangChain에서 네이버 검색 도구 연결하기 링크 ✔︎ (2부) 세션 관리와 컨텍스트 유지 전략 링크 ✔︎ (3부) OAuth 인증이 통합된 MCP 서버 구축하기 링크 ✔︎ (4부) 운영과 확장을 위한 다양한 팁 1. MCP Inspector로 서버 검증하기 MCP Inspector는 Anthropic에서 제공하는 MCP 서버 테스트·디버깅 도구입니다. GUI 환경에서 서버와 연결하여 도구 목록 확인, 도구 호출 테스트, 스트리밍 이벤트 모니터링 등을 쉽게 수행할 수 있습니다. 아래 명령어를 터미널에서 실행하면 브라우저가 자동으로 열립니다. npx @modelcontextprotocol/inspector 브라우저가 열리면 아래 절차에 따라 간단하게 MCP Inspector를 살펴볼 수 있습니다. 서버 연결 (1부) LangChain에서 네이버 검색 도구 연결하기에서 만든 MCP 서버를 연결합니다. 좌측 패널에서 다음의 값을 입력한 후, Connect 버튼을 클릭합니다. Transport Type: Streamable HTTP URL: http://127.0.0.1:8000/mcp/ 도구 목록 확인 상단 메뉴에서 Tools를 선택하고 [List Tools] 버튼을 클릭합니다. 등록된 도구 목록이 표시되며, MCP 서버에 정의된 도구들을 확인할 수 있습니다. 도구 호출 테스트 도구 목록에서 도구를 선택한 후, 우측 입력 영역에 요청 파라미터를 입력하고 실행합니다. 응답이 우측 패널에 실시간으로 표시됩니다. 다음 이미지는 MCP Inspector에서 서버 연결 후 도구 목록을 조회하고, 특정 도구를 실행한 화면 예시입니다. MCP Inspector는 이러한 단순한 호출 테스트 외에도 리소스 조회, 스트리밍 이벤트 모니터링 등의 기능을 지원하므로, MCP 서버를 다양한 방식으로 검증하고 디버깅하는 데 활용할 수 있습니다. 2. Flowise로 노코드 클라이언트 구성하기 Flowise는 MCP 서버와 연결하여 시각적 인터페이스에서 도구를 구성하고 실행할 수 있는 노코드 기반 클라이언트입니다. 기본적으로 MCP 서버와 HTTP 기반으로 통신하며, STDIO로 연결하려면 로컬 환경에 설치된 Flowise로 실행해야 합니다. 또한 Flowise에서는 OpenAI 호환 모델을 연결할 수 있으며, CLOVA Studio의 HCX-005 모델을 이용할 수 있습니다. 단, HCX-007 모델은 현재 일부 파라미터가 호환되지 않아서 연동이 불가능합니다. Flowise 계정 생성 Flowise 예제를 실행하려면 계정 생성이 필요합니다. 다만, Flowise는 필수 구성 요소가 아니며, 선택적으로 활용할 수 있습니다. 클라우드 사용: Flowise에 가입하여 계정을 생성하면 바로 이용할 수 있습니다. 로컬 설치: Node.js 환경에서 다음 명령어로 설치 후 실행할 수 있습니다. 자세한 내용은 Flowise GitHub 문서를 참고해 주세요. npm install -g flowise npx flowise start 워크플로우 생성 절차 다음 절차를 따라서 워크플로우를 생성합니다. Agentflows 시작 Agentflows에서 우측 상단의 [+ Add New] 버튼을 클릭합니다. 노드 추가 좌측 상단의 버튼을 클릭하여 Agent 노드를 드래그하여 추가합니다. 동일한 방법으로 Direct Reply 노드를 드래그하여 추가합니다. 노드 연결 Start, Agent, Direct Reply 순으로 드래그하여 연결합니다. Agent 노드 설정 Agent 노드를 더블 클릭해 노출되는 모달에서 아래 값을 입력합니다. Model: ChatOpenAI Custom ChatOpenAI Custom Parameters Connect Credential: Create New 선택 후 Credential Name을 입력하고 OpenAI API Key에는 CLOVA Studio에서 발급받은 API Key 입력 Model Name: HCX-005 BasePath: https://clovastudio.stream.ntruss.com/v1/openai Messages Message1 Role: System Content: 당신은 친절한 AI 어시스턴트입니다. 사용자의 질문에 대해 신뢰할 수 있는 정보만 근거로 삼아 답변하세요. Message2 Role: User Content: {{question}} Tools Tool: Custom MCP Custom MCP Parameters MCP Server Config: 로컬 환경에서 Flowise를 실행하는 경우에는 아래 값을 입력합니다. 만약 Flowise 클라우드(웹) 환경에서 실행한다면, ngrok 등을 통해 외부 접근이 가능한 URL을 설정해야 합니다. { "url": "http://127.0.0.1:8000/mcp/", "headers": { "Accept": "application/json, text/event-stream", "Content-Type": "application/json" } } Avaliable Actions: 우측의 새로고침 아이콘 클릭한 뒤 도구 선택 Direct Reply 노드 설정 Direct Reply 노드를 더블 클릭해 노출되는 모달에서 아래 값을 입력합니다. {{ agentAgentflow_0 }} 워크플로우 저장 및 실행 우측 상단의 저장 아이콘을 클릭해 워크플로우를 저장합니다. 메시지 아이콘을 클릭해 대화를 실행합니다. Quote ngrok은 로컬 서버를 외부에서 접근할 수 있도록 해주는 터널링 도구입니다. 먼저 공식 사이트에서 회원가입 후, 안내에 따라 ngrok을 설치하고 발급받은 인증 토큰을 등록해야 합니다. 설치와 설정이 완료되면 터미널에서 다음 명령어를 실행하여, 로컬 8000 포트를 https://xxx.ngrok-free.app 형태의 공개 URL로 매핑할 수 있습니다. ngrok http 8000 이렇게 생성된 URL은 http://xxx.ngrok-free.app/mcp/와 같이 MCP Server Config의 값으로 입력하면 됩니다. 워크플로우 실행 화면 3. MCP 도구 파라미터 설명과 타입 정의하기 파라미터 타입 정의 PEP 484 및 604 타입 힌트로 각 파라미터의 타입을 명시할 수 있습니다. 파이썬 기본 타입부터 일반적인 Pydantic 호환 타입을 대부분 사용할 수 있습니다. from fastmcp import FastMCP from typing import Literal mcp = FastMCP("Example") @mcp.tool def your_tool( param_1: str, # 문자열 param_2: str | int, # 문자열 또는 정수 param_3: Literal["A", "B"], # "A" 또는 "B"만 허용 param_4: list[str] | None # 문자열 리스트 또는 None ) -> dict: # ... return {"ok": True} 필수 및 선택 파라미터 파라미터에 기본값이 없으면 필수(required), 기본값이 있으면 선택(optional) 인자로 스키마에 정의됩니다. LLM이 이 스키마를 참고해 호출 인자를 구성합니다. from fastmcp import FastMCP from typing import Literal mcp = FastMCP("Example") @mcp.tool def your_tool( # 기본값이 없으므로 스키마에서 required로 포함됨(LLM이 반드시 생성해야만 함) param_1: str, # 필수 파라미터: 문자열. 기본값 없음 # 기본값이 있으므로 required 아님. 모든 문자열 또는 정수 허용되며, 미지정 시 "auto" param_2: str | int = "auto", # 선택 파라미터: string | int. 기본값 "auto" # 기본값이 없으므로 스키마에서 required로 포함됨. 값은 "A" 또는 "B" 중 하나만 허용 param_3: Literal["A", "B"], # 필수 파라미터: "A" 또는 "B"만 허용. 기본값 없음 # 기본값이 있으므로 required 아님. 문자열 리스트 또는 None 허용, 미지정 시 None param_4: list[str] | None = None # 선택 파라미터: list[str] 또는 None ) -> dict: # ... return {"ok": True} 파라미터 역할 정의 파라미터별 역할을 정의하기 위해, typing.Annotated를 사용할 수 있습니다. 이후 도구 스키마의 description 필드로 포함되어, LLM이 각 파라미터의 의미를 더 정확히 이해할 수 있도록 돕습니다. from fastmcp import FastMCP from typing import Literal from typing import Annotated mcp = FastMCP("Example") @mcp.tool def your_tool( param_1: Annotated[str, "파라미터 설명 1"], param_2: Annotated[str | int, "파라미터 설명 2"] = "auto", param_3: Annotated[Literal["A", "B"], "파라미터 설명 3"], param_4: Annotated[list[str] | None, "파라미터 설명 4"] = None ) -> dict: # ... return {"ok": True} 특정 파라미터 제외 exclude_args를 사용하면 특정 파라미터를 도구 스키마에서 제외하여 LLM이 해당 값을 생성하지 않도록 할 수 있습니다. 주로 user_id, auth_token처럼 LLM에 노출되면 안되거나, 호출 때마다 서버가 직접 주입해야 하는 값에 사용합니다. from fastmcp import FastMCP from typing import Literal from typing import Annotated mcp = FastMCP("Example") @mcp.tool( name="your_tool", exclude_args=["param1"] ) def your_tool( param_1: Annotated[str, "파라미터 설명 1"], param_2: Annotated[str | int, "파라미터 설명 2"] = "auto", param_3: Annotated[Literal["A", "B"], "파라미터 설명 3"], param_4: Annotated[list[str] | None, "파라미터 설명 4"] = None ) -> dict: # ... return {"ok": True} 4. 개인화 도구 설계하기 (3부) MCP 실전 쿡북: OAuth 인증이 통합된 MCP 서버 구축하기에서 설명한 대로, 사용자가 OAuth 인증을 완료하면 MCP 서버가 액세스 토큰을 안전하게 저장하고, 이후 AI 어시스턴트를 통한 요청이 들어올 때마다 인증 미들웨어가 자동으로 해당 사용자의 토큰을 찾아 제공합니다. 개발자는 복잡한 인증 과정을 신경 쓸 필요 없이 get_access_token()만 호출하면 되며, 이 토큰은 Bearer {token} 형식으로 API 요청에 자동으로 포함됩니다. 파이썬의 contextvars 덕분에 여러 사용자가 동시에 요청해도 토큰이 섞이지 않아 안전합니다. 이 구조를 활용하면 OAuth 토큰을 안전하게 재사용하면서 사용자별 맞춤 기능을 쉽게 추가할 수 있으며, 네이버뿐만 아니라 구글, 카카오, GitHub 등 OAuth를 지원하는 모든 개인화 서비스에 동일한 방식으로 MCP 서버를 구성할 수 있습니다. import os from fastmcp import FastMCP from naver import NaverProvider from dotenv import load_dotenv load_dotenv() # 환경 변수 로드 NAVER_CLIENT_ID = os.getenv("NAVER_CLIENT_ID") NAVER_CLIENT_SECRET = os.getenv("NAVER_CLIENT_SECRET") BASE_URL = os.getenv("BASE_URL") # OAuth Provider 초기화 auth = NaverProvider( client_id=NAVER_CLIENT_ID, client_secret=NAVER_CLIENT_SECRET, base_url=BASE_URL ) # MCP 서버 생성 mcp = FastMCP(name="Naver Calendar MCP", auth=auth) # 도구 정의 @mcp.tool(description="네이버 캘린더에 일정을 추가합니다.") async def create_calendar_schedule( title: str, start_datetime: str, end_datetime: str ) -> dict: from fastmcp.server.dependencies import get_access_token import urllib.request # 1. 액세스 토큰 가져오기 token = get_access_token() access_token = token.token # 2. API 요청 준비 header = "Bearer " + access_token url = "https://openapi.naver.com/calendar/createSchedule.json" # 3. iCalendar 문자열 생성 schedule_ical = f"""BEGIN:VCALENDAR VERSION:2.0 PRODID:Naver Calendar BEGIN:VEVENT DTSTART;TZID=Asia/Seoul:{start_datetime} DTEND;TZID=Asia/Seoul:{end_datetime} SUMMARY:{title} END:VEVENT END:VCALENDAR""" # 4. API 요청 전송 data = f"calendarId=defaultCalendarId&scheduleIcalString={schedule_ical}" request = urllib.request.Request(url, data=data.encode("utf-8")) request.add_header("Authorization", header) try: response = urllib.request.urlopen(request) return { "success": True, "message": "일정이 추가되었습니다." } except Exception as e: return { "success": False, "error": str(e) } # 서버 실행 if __name__ == "__main__": mcp.run(transport="streamable-http", path="/mcp") 마무리 1부(서버·클라이언트 연결), 2부(세션·컨텍스트 관리), 3부(OAuth 2.0 인증 예시)를 바탕으로 4부에서는 MCP 운영 효율을 높이는 여러 방법을 다뤘습니다. MCP의 특성을 명확히 이해하고, 서비스 목적에 맞게 설계·적용한다면, 보다 안정적이고 확장 가능한 MCP 생태계를 구축할 수 있습니다. 이제 CLOVA Studio 모델을 활용해, 직접 자신만의 MCP 서버 연동 워크플로우를 만들어 보시길 바랍니다. 🚀 MCP 실전 쿡북 4부작 시리즈 ✔︎ (1부) LangChain에서 네이버 검색 도구 연결하기 링크 ✔︎ (2부) 세션 관리와 컨텍스트 유지 전략 링크 ✔︎ (3부) OAuth 인증이 통합된 MCP 서버 구축하기 링크 ✔︎ (4부) 운영과 확장을 위한 다양한 팁 링크 복사 다른 사이트에 공유하기 More sharing options...
Recommended Posts
게시글 및 댓글을 작성하려면 로그인 해주세요.
로그인