Model Context Protocol (MCP) 및 Weave

Weave로 MCP 클라이언트와 MCP 서버 간 활동을 추적하세요

Model Context Protocol (MCP)는 AI 애플리케이션이 대규모 언어 모델(LLM)과 정보를 교환할 수 있도록 하는 표준화된 통신 프로토콜입니다. 하드웨어 호환성을 혁신했던 범용 커넥터처럼 MCP는 LLM이 다양한 데이터 소스에 접근하고 외부 도구와 상호작용할 수 있는 인터페이스를 제공하며, 새로운 서비스마다 맞춤형 통합을 구현할 필요가 없습니다.

Weave 통합을 사용하면 MCP 클라이언트와 MCP 서버 간 활동을 추적할 수 있습니다. MCP 기반 시스템 전반에서 도구 호출, 리소스 접근, 프롬프트 생성 과정을 세부적으로 관찰할 수 있습니다.

​

작동 방식

현재 이 통합 기능은 클라이언트 측과 서버 측 작업을 각각 별도로만 캡처하며, 둘 사이 상호작용에 대한 엔드 투 엔드 가시성은 제공하지 않습니다. 엔드 투 엔드 관측 가능성을 확보하기 위해 MCP에 OpenTelemetry trace 지원을 추가하는 제안이 진행 중입니다. 자세한 내용은 GitHub discussion #269를 참조하세요.

Weave 통합 기능은 핵심 메서드에 weave.op() 데코레이터를 패치하여 Model Context Protocol(MCP)의 주요 구성 요소를 자동으로 추적합니다. 구체적으로는 mcp.server.fastmcp.FastMCP 클래스와 mcp.ClientSession 클래스의 메서드를 패치합니다.

이 통합을 통해 Weave는 다음 MCP 구성 요소를 추적합니다:

• Tools
• Resources
• Prompts

​

통합 사용하기

Weave 통합은 MCP 서버와 클라이언트 모두에서 사용할 수 있습니다. 설치가 완료되면 두 줄의 코드만 추가해서 추적을 활성화할 수 있습니다. 하나는 weave를 import하는 코드이고, 다른 하나는 Weave를 초기화하는 코드입니다.

​

사전 준비 사항

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

pip install -qq "mcp[cli]" weave

​

구성

MCP 통합은 환경 변수로 설정할 수 있습니다:

• MCP_TRACE_LIST_OPERATIONS: 서버와 클라이언트 양쪽에서 목록 작업(list_tools, list_resources, list_prompts)을 추적하려면 true로 설정합니다.

​

서버 측 통합

MCP 서버를 추적하려면 기존 FastMCP 설정에 두 줄을 추가합니다. 하나는 Weave를 import하는 코드이고, 다른 하나는 클라이언트를 초기화하는 코드입니다. 이 두 줄을 추가하면 도구, 리소스, 프롬프트 관련 작업이 자동으로 추적됩니다.

# Weave 가져오기 (추적에 필요)
import weave
from mcp.server.fastmcp import FastMCP

# 프로젝트 이름으로 Weave 초기화
weave_client = weave.init("my-project")

# MCP 서버 설정
mcp = FastMCP("Demo")

# 도구 정의 (이 호출은 추적됨)
@mcp.tool()
def add(a: int, b: int) -> int:
    """두 숫자를 더합니다."""
    return a + b

# 리소스 정의 (이 호출은 추적됨)
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """개인화된 인사말을 반환합니다."""
    return f"Hello, {name}!"

# 프롬프트 정의 (이 호출은 추적됨)
@mcp.prompt()
def review_code(code: str) -> str:
    """코드 검토를 위한 프롬프트를 반환합니다."""
    return f"Please review this code:\n\n{code}"

# 서버 시작
mcp.run(transport="stdio")

​

클라이언트 측 통합

클라이언트 측에서도 추적을 위해 필요한 변경 사항은 두 가지뿐입니다. Weave를 import한 뒤 초기화하면 됩니다. 모든 도구 호출, 리소스 액세스, 프롬프트 요청은 자동으로 추적됩니다.

# Weave 가져오기 (추적에 필요)
import weave
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# 프로젝트 이름으로 Weave 초기화
weave_client = weave.init("my-project")

# MCP 클라이언트 설정 및 실행
async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        # 세션 초기화
        await session.initialize()
        
        # 도구 호출 (추적됨)
        result = await session.call_tool("add", arguments={"a": 1, "b": 2})
        
        # 리소스 읽기 (추적됨)
        resource = await session.read_resource("greeting://user")
        
        # 프롬프트 가져오기 (추적됨)
        prompt = await session.get_prompt("review_code", arguments={"code": "print('Hello')"})

​

튜토리얼: mcp_demo 예제

mcp_demo 예제는 Model Context Protocol (MCP)과 Weave를 연동하여 트레이싱하는 방법을 보여줍니다. 클라이언트와 서버 컴포넌트 모두를 계측해 상호작용에 대한 자세한 트레이스를 기록하는 방법을 시연합니다.

​

예제 실행하기

1. docs 저장소를 클론하고 mcp_demo 예제로 이동합니다:

   git clone https://github.com/wandb/docs
   cd docs/weave/examples/mcp_demo
   

   이 예제는 다음 두 개의 주요 파일로 구성됩니다:

   • example_server.py: FastMCP로 구현된 데모 MCP 서버입니다. 도구, 리소스, 프롬프트를 정의합니다.
   • example_client.py: 서버에 연결해 해당 구성 요소들과 상호작용하는 클라이언트입니다.

2. 필요한 의존성을 수동으로 설치합니다:

   pip install mcp[cli] weave
   

3. 데모를 실행합니다:

   python example_client.py example_server.py
   

   이 명령은 클라이언트와 서버를 모두 실행합니다. 클라이언트는 다양한 기능을 테스트할 수 있는 대화형 CLI를 시작합니다.

​

클라이언트 CLI 명령어

클라이언트 인터페이스는 다음 명령어들을 지원합니다:

Command	Description
tools	사용 가능한 도구 목록을 표시합니다
resources	사용 가능한 리소스 목록을 표시합니다
prompts	사용 가능한 프롬프트 목록을 표시합니다
add <a> <b>	두 숫자를 더합니다
bmi <weight> <height>	체질량지수(Body Mass Index)를 계산합니다
weather <city>	지정한 도시에 대한 날씨 데이터를 가져옵니다
greeting <name>	사용자 맞춤 인사말을 반환합니다
user <id>	사용자 프로필을 조회합니다
config	앱 구성 정보를 가져옵니다
code-review <code>	코드 리뷰용 프롬프트를 생성합니다
debug <error>	디버깅용 프롬프트를 생성합니다
demo	사용 가능한 모든 기능의 전체 데모를 실행합니다. 각 기능을 순차적으로 실행하고 Weave UI에서 상호작용의 전체 트레이스 타임라인을 생성합니다.
q	세션을 종료합니다

​

예제 이해하기

example_server.py 서버는 다음을 정의합니다:

• 도구(Tools): add(), calculate_bmi(), fetch_weather() 같은 함수
• 리소스(Resources): greeting://{name}, config://app, users://{id}/profile 같은 엔드포인트
• 프롬프트(Prompts): review_code() 및 debug_error() 같은 템플릿

클라이언트를 weave.init()으로 초기화하면, 모든 서버 측 작업은 Weave에 의해 자동으로 추적됩니다.

example_client.py 클라이언트는 다음을 보여줍니다:

• MCP 서버에 연결하기
• 사용 가능한 도구, 리소스, 프롬프트 검색하기
• 매개변수를 사용해 도구 호출하기
• 리소스 URI에서 읽기
• 인자를 사용해 프롬프트 생성하기
• 사용자 정의 메서드/함수와 함께 weave.op()를 사용하는 방법

Weave는 클라이언트 측의 모든 호출을 추적하여 클라이언트와 서버 간 상호작용에 대한 전체적인 관점을 제공합니다.

​

자주 묻는 질문

​

왜 MCP 트레이싱이 필요한가요?

LLM 애플리케이션 개발자인 경우, 다음 세 가지 범주 중 하나에 해당합니다:

• MCP 서버 측 개발자: MCP 클라이언트에 여러 도구, 리소스, 프롬프트를 노출하려고 합니다. 기존 애플리케이션의 도구, 리소스 등을 노출하거나 에이전트를 구축했으며, 여러 에이전트를 오케스트레이션하는 오케스트레이터 에이전트를 사용하고 있을 수 있습니다.

• MCP 클라이언트 측 개발자: 클라이언트 측 애플리케이션을 여러 MCP 서버에 연결하려고 합니다. 클라이언트 측 로직의 핵심은 어떤 도구를 호출할지, 어떤 리소스를 가져올지를 결정하기 위해 LLM 호출을 수행하는 것입니다.

• MCP 서버 및 클라이언트 개발자: 서버와 클라이언트를 모두 개발하고 있습니다.

첫 두 범주 중 하나에 해당한다면, 각 도구가 언제 호출되는지, 실행 흐름이 어떻게 보이는지, 서버 또는 클라이언트 측 로직의 다양한 구성 요소에 대한 토큰 수와 지연 시간(latency)이 어떻게 되는지 알고 싶어집니다.

서버와 클라이언트를 모두 개발 중이라면, 통합된 트레이스 타임라인을 볼 수 있는 기능이 서버 및 클라이언트 측 로직을 빠르게 반복 개선하는 데 도움이 됩니다.

어떤 경우든, 관측(Observability) 레이어를 두면 다음을 수행할 수 있습니다:

• 애플리케이션을 빠르게 반복 개선
• 워크플로 또는 실행 로직 감사
• 병목 구간 식별