MCP 활용

Model Context Protocol을 통한 자연어 인터페이스

---

MCP란?

MCP (Model Context Protocol)는 AI 애플리케이션이 외부 도구와 데이터 소스에 안전하게 연결할 수 있도록 하는 개방형 프로토콜입니다. Anthropic이 개발했으며, LLM이 자연어로 다양한 시스템과 상호작용할 수 있게 합니다.

주요 특징

• 자연어 인터페이스: 복잡한 API 호출을 자연어로 대체
• 도구 통합: 데이터베이스, API, 파일 시스템 등 다양한 리소스 접근
• 컨텍스트 유지: 대화 중 상태 및 데이터 지속성 제공
• 타입 안전성: JSON Schema 기반 입력 검증

---

VSS Feature Store와 MCP

MCP를 통해 다음 작업을 자연어로 수행 가능:

• 자연어로 비디오 캡션 검색
• 배치 등록 및 메타데이터 조회
• 모델별 결과 비교
• 복잡한 필터링 및 집계 작업

---

Cursor/Claude Code에서 사용하기

MCP 서버를 Claude Code와 Cursor에서 사용하는 방법입니다. 설정 포맷은 동일하며, 파일 위치와 활성화 방법만 다릅니다.

---

설정 파일 위치

도구	설정 파일 경로
Claude Code	~/.claude.json
Cursor	~/.cursor/mcp.json

---

설정 템플릿

다음 설정을 위 파일에 추가하거나 생성합니다:

{
  "mcpServers": {
    "vss-feature-store": {
      "command": "/path/to/your/mantis-ml-platform/.venv/bin/python",
      "args": [
        "/path/to/your/mantis-ml-platform/services/svc-vss/data/feast/mcp_server.py"
      ],
      "env": {
        "PYTHONPATH": "/path/to/your/mantis-ml-platform/services/svc-vss/data/feast",
        "VIRTUAL_ENV": "/path/to/your/mantis-ml-platform/.venv",
        "AWS_ACCESS_KEY_ID": "minioadmin",
        "AWS_SECRET_ACCESS_KEY": "minioadmin",
        "AWS_ENDPOINT_URL_S3": "http://your-minio-endpoint:9000",
        "FEAST_S3_ENDPOINT_URL": "http://your-minio-endpoint:9000"
      }
    }
  }
}

경로 수정 필요

• /path/to/your/mantis-ml-platform를 실제 프로젝트 절대 경로로 수정
• http://your-minio-endpoint:9000을 실제 MinIO 엔드포인트로 수정

---

실제 환경 예시

아래는 실제 개발 환경에서 사용하는 설정 예시입니다:

{
  "mcpServers": {
    "vss-feature-store": {
      "command": "/home/ail/pyler/mantis-ml-platform/.venv/bin/python",
      "args": [
        "/home/ail/pyler/mantis-ml-platform/services/svc-vss/data/feast/mcp_server.py"
      ],
      "env": {
        "PYTHONPATH": "/home/ail/pyler/mantis-ml-platform/services/svc-vss/data/feast",
        "VIRTUAL_ENV": "/home/ail/pyler/mantis-ml-platform/.venv",
        "AWS_ACCESS_KEY_ID": "minioadmin",
        "AWS_SECRET_ACCESS_KEY": "minioadmin",
        "AWS_ENDPOINT_URL_S3": "http://andrew-minio-2025-12-03-svc.dev.idc.k8s:9000",
        "FEAST_S3_ENDPOINT_URL": "http://andrew-minio-2025-12-03-svc.dev.idc.k8s:9000"
      }
    }
  }
}

---

활성화 방법

Claude Code

1. ~/.claude.json 파일에 위 설정 추가
2. Claude Code 재시작
3. 자동으로 MCP 서버 등록 완료

Cursor

1. ~/.cursor/mcp.json 파일 생성 후 위 설정 작성
2. Cursor Settings (Cmd/Ctrl + ,) 열기
3. "Tools & MCP" 탭 → "Enable MCP" 토글 활성화
4. Cursor 재시작

---

연결 확인

설정 후 다음과 같이 질문하여 연결을 확인할 수 있습니다:

"현재 사용 가능한 MCP 도구가 뭐야?"

또는

"vss-feature-store MCP 서버가 연결되었는지 확인해줘"

---

문제 해결

MCP 서버가 연결되지 않는 경우

1. Python 경로 확인

   which python  # Virtual environment의 python 경로 확인
   

2. mcp_server.py 파일 존재 확인

   ls -la /path/to/mantis-ml-platform/services/svc-vss/data/feast/mcp_server.py
   

3. 환경 변수 확인

4. PYTHONPATH가 올바른지 확인

5. MinIO 엔드포인트가 접근 가능한지 확인

6. 로그 확인

7. Claude Code: ~/.claude/logs/
8. Cursor: Settings → Output → MCP Logs

권한 문제

# mcp_server.py 실행 권한 부여
chmod +x /path/to/mantis-ml-platform/services/svc-vss/data/feast/mcp_server.py

---

실제 사용 예시

(1) 사용 가능한 기능 확인

사용자 질문:

"현재 사용할 수 있는 기능이 뭐야?"

Claude 응답:

• 비디오 관리: get_video, get_all_videos
• 캡션 조회: search_metadata, get_captions, get_captions_batch
• 캡션 등록: register_captions, register_captions_batch
• 지원하는 Feature View: video_description, audio_transcript, caption_summary

---

(2) 기능 사용 방법 확인

사용자 질문:

"배치 등록 기능을 사용하는 방법은 뭐야?"

Claude 응답:

• Function: register_captions_batch
• JSON 파일 형식 설명
• 필드 설명 (uuid, mp4_source, model, segments)
• 반환값 설명

---

(3) JSON 파일 배치 등록

사용자 질문:

/home/ail/pyler/sync_odk/output/gemini_high_caption_summary.json
/home/ail/pyler/sync_odk/output/gemini_medium_caption_summary.json
위 파일들을 caption summary에 등록해줄래?

결과:

두 파일 모두 성공적으로 등록됨 (Fine/Coarse 설정)

---

(4) 등록된 비디오 목록 확인

사용자 질문:

"등록된 비디오 목록을 확인하고 싶어"

결과:

등록된 비디오 UUID 리스트와 각 비디오의 세그먼트 수, YouTube 링크 제공

---

(5) 특정 비디오 메타데이터 조회

사용자 질문:

"WuFL2bJm2yo 비디오의 caption summary 메타데이터를 보고 싶어"

결과:

해당 비디오에 2개 버전 존재 (Fine 위드/Coarse 설정):

• Fine: 45개 세그먼트 (gemini_fine.yaml)
• Coarse: 24개 세그먼트 (gemini_coarse.yaml)

---

(6) 캡션 상세 조회

사용자 질문:

WuFL2bJm2yo 비디오, gemini 모델, coarse 설정의
caption summary 결과를 테이블 형태로 보고 싶어

결과:

24개 세그먼트의 상세 캡션이 테이블 형태로 표시됨 (index, start, end, text)

---

MCP의 장점

1. 자연어 인터페이스

복잡한 API 호출 대신 자연어로 요청 가능:

• ❌ api.search_metadata(feature_view='caption_summary', models=['gemini'])
• ✅ "gemini 모델로 처리된 caption summary 자료를 찾아줘"

2. 컨텍스트 유지

이전 결과를 자동으로 활용:

"WuFL2bJm2yo 비디오의 메타데이터를 보여줘"
→ [메타데이터 조회]

"이 비디오의 coarse config 캡션도 보여줘"
→ [자동으로 이전 UUID 사용]

3. 복잡한 워크플로우

여러 도구를 조합한 작업 가능:

"24년 8월 14일에 등록된 caption summary 데이터를 모두 조회해서,
어떤 종류의 영상들이 올라왔는지 핵심 주제로 요약해줘"

→ search_metadata (시간 필터)
→ get_captions_batch (전체 조회)
→ 분석 및 비교 테이블 생성

---

다음 단계

• API 레퍼런스 - 전체 API 문서
• 시작하기 - 기본 사용법
• GitHub README - MCP 설정 가이드 (예정)