Skip to main content
Colab에서 열기 Model Context Protocol (MCP)은 AI 애플리케이션이 대규모 언어 모델(LLM)과 정보를 주고받을 수 있게 해 주는 표준화된 통신 프로토콜입니다. MCP는 LLM이 데이터 소스에 액세스하고 외부 도구와 상호 작용할 수 있는 인터페이스를 제공하므로, 새로운 서비스마다 맞춤형 인테그레이션을 따로 구현할 필요가 없습니다. Weave 인테그레이션을 사용하면 MCP 클라이언트와 MCP 서버 간의 활동을 트레이스할 수 있습니다. MCP 기반 시스템 전반의 도구 Call, 리소스 액세스, 프롬프트 생성을 자세히 파악할 수 있으므로 MCP 애플리케이션을 디버그하고, 감사하고, 최적화할 수 있습니다. 이 가이드에서는 인테그레이션의 작동 방식과 서버 및 클라이언트 측에서 트레이싱을 활성화하는 방법을 설명하고, 직접 실행해 볼 수 있는 전체 예시를 단계별로 안내합니다.

작동 방식

이 인테그레이션은 클라이언트 측 오퍼레이션과 서버 측 오퍼레이션을 각각 캡처하지만, 둘 사이의 상호작용을 엔드 투 엔드로 확인할 수는 없습니다. 엔드 투 엔드 관측성을 구현하기 위해 MCP에 OpenTelemetry 트레이스 지원을 추가하자는 제안이 현재 논의되고 있습니다. 자세한 내용은 GitHub discussion #269를 참조하세요.
Weave 인테그레이션은 핵심 메서드를 weave.op() 데코레이터로 패치하여 Model Context Protocol(MCP)의 주요 컴포넌트를 자동으로 트레이스합니다. 구체적으로는 mcp.server.fastmcp.FastMCP 및 mcp.ClientSession 클래스의 메서드를 패치합니다. 이 인테그레이션을 사용하면 Weave에서 다음 MCP 컴포넌트를 트레이스할 수 있습니다. mcp_trace_timeline.png

인테그레이션 사용하기

Weave 인테그레이션은 MCP 서버와 클라이언트 모두에서 작동합니다. 설치한 후에는 코드 두 줄만 추가하면 트레이싱을 활성화할 수 있습니다. 한 줄은 weave를 임포트하고, 다른 한 줄은 이를 초기화합니다.

사전 요구 사항

시작하기 전에 필요한 패키지를 설치하세요.

설정

MCP_TRACE_LIST_OPERATIONS 환경 변수로 MCP 인테그레이션을 설정하세요. 이 값을 true로 설정하면 서버와 클라이언트 양쪽에서 목록 오퍼레이션(list_tools, list_resources, list_prompts)을 트레이스합니다.

서버 측 인테그레이션

MCP 서버를 구축하거나 계측하는 경우 이 섹션을 참고하세요. MCP 서버를 트레이스하려면 기존 FastMCP 설정에 Weave를 임포트하는 코드와 클라이언트를 초기화하는 코드, 이렇게 두 줄만 추가하면 됩니다. 추가하면 Weave가 도구, 리소스, 프롬프트 오퍼레이션을 자동으로 트레이스합니다.

클라이언트 측 인테그레이션

MCP 클라이언트를 구축하거나 계측하는 경우 이 섹션을 참고하세요. 클라이언트 측에서도 트레이싱을 사용하려면 두 가지만 변경하면 됩니다. Weave를 임포트하고 초기화하세요. Weave는 모든 도구 Call, 리소스 액세스, 프롬프트 요청을 자동으로 트레이스합니다.

튜토리얼: mcp_demo 예시

mcp_demo 예시는 트레이싱을 위해 MCP와 Weave를 인테그레이션하는 방법을 보여 줍니다. 클라이언트와 서버 컴포넌트를 모두 계측하여 두 컴포넌트 간 상호 작용을 상세한 트레이스로 캡처하는 방법을 소개합니다. 이 코드를 실행해 보면 Weights & Biases UI에서 MCP 애플리케이션 양쪽의 트레이스를 확인할 수 있으며, 자신의 프로젝트에 맞게 응용할 수 있는 구체적인 레퍼런스도 얻을 수 있습니다.

예시 실행하기

  1. docs 저장소를 클론한 후 mcp_demo 예시 디렉터리로 이동하세요:
    이 예시는 두 개의 주요 파일로 구성되어 있습니다:
    • example_server.py: FastMCP로 빌드한 데모 MCP 서버입니다. 도구(tools), 리소스(resources), 프롬프트(prompts)를 정의합니다.
    • example_client.py: 서버에 연결하여 서버의 컴포넌트와 상호작용하는 클라이언트입니다.
  2. 필요한 의존성을 직접 설치하세요:
  3. 데모를 실행하세요:
    이 명령을 실행하면 클라이언트와 서버가 함께 시작됩니다. 클라이언트는 대화형 CLI를 실행하며, 여기에서 다양한 기능을 테스트할 수 있습니다.

클라이언트 CLI 명령어

클라이언트 인터페이스는 다음 명령어를 지원합니다.

예시 개요

example_server.py 서버는 다음을 정의합니다.
  • 도구: add(), calculate_bmi(), fetch_weather() 같은 함수
  • 리소스: greeting://{name}, config://app, users://{id}/profile 같은 엔드포인트
  • 프롬프트: review_code(), debug_error() 같은 템플릿
weave.init()으로 클라이언트를 초기화하면 Weave가 모든 서버 측 오퍼레이션을 자동으로 트레이스합니다. example_client.py 클라이언트는 다음 방법을 보여 줍니다.
  • MCP 서버에 연결하기
  • 사용 가능한 도구, 리소스, 프롬프트 탐색하기
  • 매개변수를 전달해 도구 호출하기
  • 리소스 URI에서 데이터 조회하기
  • 인수를 전달해 프롬프트 생성하기
  • 맞춤형 메서드 및 함수에 weave.op() 사용하기
Weave는 모든 클라이언트 측 Call을 트레이스하므로 클라이언트와 서버 간 상호 작용 전체를 한눈에 확인할 수 있습니다.

FAQ

이 섹션에서는 Weave의 MCP 트레이싱을 사용하는 이유와 사용 방법에 대해 자주 묻는 질문을 다룹니다.

MCP 트레이싱이 필요한 이유

LLM 애플리케이션 개발자는 다음 세 가지 유형 중 하나에 해당합니다.
  • MCP 서버 측 개발자: 여러 도구, 리소스, 프롬프트를 MCP 클라이언트에 노출하려는 경우입니다. 기존 애플리케이션의 도구와 리소스를 노출하거나, 직접 에이전트를 구축했거나, 오케스트레이터 에이전트가 여러 에이전트를 조율하는 구조를 운영하고 있을 수 있습니다.
  • MCP 클라이언트 측 개발자: 클라이언트 측 애플리케이션을 여러 MCP 서버에 연결하려는 경우입니다. 클라이언트 측 로직의 핵심은 LLM Call을 통해 어떤 도구를 호출할지, 어떤 리소스를 가져올지 결정하는 것입니다.
  • MCP 서버 및 클라이언트 개발자: 서버와 클라이언트를 모두 개발하는 경우입니다.
처음 두 유형 중 하나에 해당한다면 각 도구가 언제 호출되는지, 실행 플로우가 어떻게 이루어지는지, 서버 또는 클라이언트 측 로직을 구성하는 각 컴포넌트의 토큰 수와 지연 시간은 얼마인지 알고 싶을 것입니다. 서버와 클라이언트를 모두 개발한다면 통합된 트레이스 타임라인을 활용해 서버 측과 클라이언트 측 로직을 함께 반복적으로 개선할 수 있습니다. 어떤 경우든 관측성 계층을 사용하면 다음과 같은 작업을 할 수 있습니다.
  • 애플리케이션을 반복적으로 개선합니다.
  • 워크플로 또는 실행 로직을 감사합니다.
  • 병목 지점을 파악합니다.
마지막 수정일 2026년 9월 30일