Weave MCP Server Client Trace

🚀 Weaving MCP Server and Client Association Tracking

This repository is derived from the example in Arize-ai/phoenix and has been modified for export to wandb/weave. Note: There is a race condition issue that sometimes causes the tool to malfunction during the OpenAI call step. This issue also exists in the original code and is not introduced by Weave.

🚀 Quick Start

✨ Features

This project enables end-to-end tracking between MCP clients and servers, leveraging OpenTelemetry to provide full observability across distributed systems.

📦 Installation

Set up the environment:

First, run cp .env.example .env Set the relevant keys in the new environment file as instructed.

Install dependencies:

• uv: uv sync
• pip: pip install -r requirements.txt

💻 Usage Examples

Run the client and export traces

• uv: uv run client.py
• python: python client.py

📚 Documentation

How to Implement End-to-End Tracking between MCP Clients and Servers (from Arize)

This tutorial demonstrates how to propagate OpenTelemetry (OTEL) context between MCP clients and servers for full observability. The openinference-instrumentation-mcp package enables this by providing instrumentation for both client and server components.

What is MCP and Why Do We Need Distributed Tracing?

One of the main advantages of MCP is to connect information between AI models and different services, machines, and programming languages. This distributed approach offers several benefits:

1. Extend AI capabilities: Enable models to connect to specialized knowledge and data sources beyond their training data.
2. Plug-and-play components: Add new context providers without retraining the model.
3. Multi-language support: Implement context providers in any programming language while maintaining compatibility.

The challenge is that debugging becomes difficult when requests flow through multiple services. How can we track the full journey of a request across the system to identify issues?

How to Use OpenTelemetry for MCP Tracing

OpenTelemetry addresses the challenges of cross-service tracing in the following ways:

• Retain context between services: Maintain the trace ID and relationships between different components.
• Automatically handle context across network boundaries: Automatically handle context in network requests.
• Support multiple languages: Use a standardized format compatible with any programming language.

When the client calls the server with proper instrumentation:

1. The client creates a span to track the operation.
2. The OTEL context is automatically passed along with the MCP request.
3. The server continues the same trace without interruption.
4. All context providers inherit this trace context.
5. You can see the full interaction as a connected trace in Phoenix.

This visibility is crucial for debugging complex AI systems, optimizing performance bottlenecks, and understanding the impact of different components on application behavior.

Setup

When properly instrumented, the trace context automatically propagates across the MCP client-server boundary, allowing you to:

• Track requests from the client to the server in a single trace.
• Observe latency at various stages of the request lifecycle.
• Debug any issues across service boundaries.

Environment Setup

1. Switch to this directory:

cd tutorials/mcp/tracing_between_mcp_client_and_server

2. Install the required dependencies:

pip install -r requirements.txt

Run the Example

1. Run Phoenix locally or connect to an online Phoenix instance. If you are using an authenticated online Phoenix instance, set the PHOENIX_API_KEY.
2. Update your .env file with the OPENAI_API_KEY and PHOENIX-related parameters.
3. Run the following command to start the service:

uv run client.py

4. Open your browser and visit http://localhost:8000

Code Explanation

• client.py: This is a simple MCP client for sending requests to Phoenix for processing.
• server.py: This is a basic MCP server for receiving and processing requests from the client.

By following the above steps, you can easily set up and run an MCP client and server with tracing capabilities.