MCP 101

Model Context Protocol 이해와 활용

MCP 101: Model Context Protocol 이해와 활용Permalink

Model Context Protocol(MCP)은 AI 에이전트와 외부 도구를 연결하는 JSON-RPC 기반 프로토콜입니다. 이 글에서는 MCP의 개념, 사용 시기, 다른 API와의 차이점, 동적 디스크립션 확인 및 디버깅 방법(SSE, stdout, Inspector 포함), 그리고 mcp-filesystem을 활용한 파일 핸들링 예제를 다룹니다. 또한 Claude와 VSCode Cline을 사용한 테스트 방법과 프롬프트 예제를 제공합니다.

1. MCP란 무엇인가?Permalink

MCP(Model Context Protocol)는 AI 모델(예: LLM)이 파일 시스템, SaaS 앱, 데이터베이스 등 외부 도구와 상호작용하도록 설계된 프로토콜입니다. JSON-RPC를 기반으로 하며, AI의 실시간 데이터 조회와 작업 수행에 최적화되어 있습니다.

주요 기능Permalink

• 동적 도구 탐색: 도구가 JSON 메타데이터로 자신의 기능을 제공하여 AI가 자동으로 이해하고 활용.
• 양방향 통신: WebSocket 또는 SSE(Server-Sent Events)를 통해 실시간 상호작용 지원.
• AI 중심 설계: AI의 의도(intent)를 기반으로 적합한 도구를 동적으로 호출.

사용 시기Permalink

MCP는 다음과 같은 경우에 적합합니다:

• AI가 외부 리소스(예: GitHub, Google Drive)에 접근하거나 작업을 수행할 때.
• 새로운 도구를 동적으로 추가하거나 복잡한 워크플로우를 자동화할 때.
• 예: AI가 “파일을 읽고 Slack에 공유”하거나 “GitHub에서 코드 검색”하는 작업.

2. MCP와 다른 API의 차이점Permalink

MCP는 REST API, SOAP와 비교해 AI 중심의 유연성을 제공합니다. 아래는 셀프 디스크립션(self-description)을 중심으로 주요 차이점입니다.

MCP의 강점Permalink

• 동적 탐색: 도구가 기능(예: 함수, 파라미터)을 JSON으로 설명하여 AI가 즉시 적응.
• AI 친화적: AI의 자연어 요청(예: “파일 읽기”)을 컨텍스트로 해석해 도구 호출.
• 확장성: 새로운 도구(예: Google Calendar → Notion API) 추가가 쉬움.

3. MCP 인터페이스: SSE와 stdoutPermalink

MCP는 WebSocket 외에도 SSE(Server-Sent Events)와 stdout을 인터페이스로 지원하여 서버와 클라이언트 간 통신을 유연하게 처리합니다.

SSE(Server-Sent Events)Permalink

• SSE는 서버가 클라이언트로 단방향 이벤트 스트림을 전송하는 HTTP 기반 기술입니다. MCP는 SSE를 사용해 도구 호출 결과나 로그를 실시간으로 전달합니다.
• 특징:
  • 경량화된 통신, WebSocket보다 설정 간단.
  • 도구 실행 상태(예: 파일 읽기 완료)를 실시간으로 스트리밍.
  • 브라우저 호환성 뛰어남.
• 사용 예:
  • AI가 파일 쓰기를 요청하면, SSE를 통해 “쓰기 시작”, “쓰기 완료” 이벤트를 수신.
  • 예: event: file_write, data: {"status": "completed"}.

stdoutPermalink

• MCP 서버는 실행 로그나 디버깅 정보를 표준 출력(stdout)으로 기록합니다. 로컬 테스트 시 유용하며, 터미널에서 실시간 확인 가능.
• 특징:
  • 간단한 디버깅에 적합, 별도 설정 불필요.
  • JSON-RPC 요청/응답, 오류 메시지 출력.
  • 예: INFO: file_read(path="test.txt") -> "Hello, MCP!".
• 사용 예:
  • MCP 서버 실행 시 터미널에서 도구 호출 로그 확인.
  • 디버깅 중 예상치 못한 오류(예: 파일 경로 오류) 추적.

4. Inspector를 활용한 디스크립션 확인 및 디버깅Permalink

MCP Inspector는 MCP 서버를 테스트하고 디버깅하는 웹 기반 도구로, 동적 디스크립션 조회와 실시간 상호작용을 지원합니다.

• https://github.com/modelcontextprotocol/inspector

실행 방법Permalink

• 설치 없이 실행: npx를 사용해 Inspector를 즉시 실행.
  • 기본 명령어:

    npx @modelcontextprotocol/inspector node path/to/server/index.js  
    

  • 예: 로컬 MCP 서버(build/index.js) 실행.

    npx @modelcontextprotocol/inspector build/index.js  
    

  • 환경 변수 지정:

    CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector build/index.js  
    

• 포트 설정:
  • 클라이언트 UI: 기본 포트 5173(예: http://localhost:5173).
  • 프록시 서버: 기본 포트 3000.
  • 커스텀 포트 설정 가능(위 예시 참조).
• 패키지 기반 실행: NPM/PyPI 패키지로 실행.
  • 예: mcp-filesystem 서버.

    npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem /path/to/allowed/files  
    

• 실행 환경:
  • Node.js 설치 필요.
  • MCP 서버가 로컬 또는 원격으로 실행 중이어야 함.

알 수 있는 정보Permalink

• 도구 메타데이터:
  • Inspector UI의 “Tools” 탭에서 describe_tools 결과를 시각적으로 확인.
  • 예: file_read의 설명(“Read content of a file”), 파라미터(path: string), 반환 형식.
• 서버 상태:
  • 연결 상태, 실행 중인 도구 목록, 서버 로그.
  • SSE(Server-Sent Events)를 통한 실시간 이벤트 스트림(예: event: file_write, data: {"status": "completed"}).
• 호출 결과:
  • 특정 도구(예: file_write) 호출 시 입력값과 응답 확인.
  • 오류 코드(예: -32602 → 잘못된 파라미터)와 메시지.
• 구성 설정:
  • Inspector UI의 “Configuration” 버튼으로 프록시 주소, 인증 토큰 등 설정 조회/변경.
  • 예: SSE 연결에 Bearer 토큰 설정 가능.

디버깅 과정Permalink

1. 도구 테스트:
   • “Tools” 탭에서 도구 선택(예: file_write).
   • 입력값 입력(예: path: "test.txt", content: "Debug test").
   • 실행 후 응답 확인(성공 여부, 결과 데이터).
2. 로그 모니터링:
   • SSE 스트림과 stdout 로그를 UI에서 실시간 확인.
   • 예: event: file_read, data: {"content": "Hello, MCP!"}.
3. 오류 추적:
   • 오류 탭에서 JSON-RPC 오류 코드와 메시지 분석.
   • 예: {"error": {"code": -32602, "message": "Invalid path"}}.
4. 서버 재시작:
   • Inspector에서 명령어 인수/환경 변수 수정 후 서버 재시작 가능.
   • 예: CLIENT_PORT=8081 npx ...로 포트 변경.

추가 고려사항Permalink

• 보안: Inspector의 프록시 서버는 로컬 프로세스 실행 권한을 가지므로, 신뢰할 수 없는 네트워크에 노출시키지 않음.
• 인증: SSE 연결 시 UI에서 Bearer 토큰 입력 가능, Authorization 헤더로 전송.
• 확장성: 복잡한 서버(예: 다중 도구)에서도 메타데이터를 체계적으로 관리.

🚀 playwright mcp 테스트 예제Permalink

$ npx @modelcontextprotocol/inspector npx @playwright/mcp@latest
...
Starting MCP inspector...
⚙️ Proxy server listening on port 6277
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀

결론Permalink

MCP(Model Context Protocol)는 AI와 외부 도구를 동적으로 연결하는 강력한 프로토콜입니다. 동적 디스크립션, SSE, stdout, Inspector를 활용하면 도구 탐색과 디버깅이 간편해집니다. mcp-filesystem 예제를 통해 파일 핸들링을 구현하고, Claude와 VSCode Cline으로 테스트하면 MCP의 유연성을 체감할 수 있습니다.

파일 관리, SaaS 통합, 복잡한 워크플로우 자동화 등 다양한 시나리오에서 MCP를 활용하려면, SSE와 Inspector를 적극 사용해 실시간 모니터링과 디버깅을 강화하세요. 추가로 궁금한 점이 있다면, 특정 도구(예: mcp-github)나 워크플로우를 알려주시면 더 다뤄보겠습니다!