Weave MCP Server + Client Linked Traces:

Weave MCP 服务 + 客户端关联追踪：

此仓库取自 Arize-ai/phoenix 中的示例，并经过调整以导出到 wandb/weave。 注意：存在一个竞争条件，有时会导致工具在 OpenAI 调用步骤运行失败。原始版本中也存在此错误，并非 weave 引入的。

设置环境：

首先运行 cp .env.example .env 按照说明，在新建的 env 文件中设置相关密钥。

安装依赖项：

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

运行客户端并导出追踪

• uv：uv run client.py
• python：python client.py

（摘自 Arize）如何为 MCP 客户端-服务端应用实现端到端追踪

本教程将介绍如何在 MCP 客户端和服务端之间传递 OpenTelemetry（OTEL）上下文，从而实现完整的可观测性。openinference-instrumentation-mcp 包通过为客户端和服务端组件提供插桩来实现这一点。

什么是 MCP？为什么需要分布式追踪？

Anthropic 的 Model Context Protocol（MCP）架构的一项主要优势，是能够将 AI 模型与不同服务、机器和编程语言中的信息连接起来。这种分布式方式有以下几项优势：

1. 拓展 AI 能力：将模型连接到训练数据之外的专业知识和数据源
2. 即插即用组件：无需重新训练模型即可添加新的上下文提供方
3. 多语言支持：使用任何编程语言实现上下文提供方，同时保持兼容性

挑战是什么？当请求流经多个服务时，调试会变得困难。如何追踪请求的完整流程，以确定问题发生的位置？

如何使用 OpenTelemetry 进行 MCP 追踪

OpenTelemetry 通过以下方式解决跨服务追踪难题：

• 跨服务保留上下文：在不同组件之间维护追踪 ID 和关联关系
• 跨越网络边界：自动处理网络请求中的上下文
• 支持多种语言：使用兼容任何编程语言的标准化格式

当客户端通过正确的插桩调用服务端时：

1. 客户端创建一个 span 来追踪该操作
2. OTEL 上下文会随 MCP 请求自动传递
3. 服务端继续同一条追踪，不会中断
4. 所有上下文提供方都会继承此追踪上下文
5. 你可以在 Phoenix 中将完整交互作为一条关联追踪查看

这种可见性对于排查复杂 AI 系统的问题、优化性能瓶颈，以及了解不同组件如何影响应用行为至关重要。

设置

完成正确的插桩后，追踪上下文会自动跨越 MCP 客户端-服务端边界传递，从而让你能够：

• 在一条追踪中跟踪从客户端到服务端的请求
• 观察请求生命周期不同阶段的延迟
• 调试跨越服务边界的问题

环境设置

1. 导航到此目录：

   cd tutorials/mcp/tracing_between_mcp_client_and_server
   

2. 安装所需依赖项：

   pip install -r requirements.txt
   

运行示例

1. 在本地运行 Phoenix，或连接到在线实例

2. 在 .env 文件中设置 OPENAI_API_KEY 和 PHOENIX_COLLECTOR_ENDPOINT。如果使用在线 Phoenix 实例或启用了身份验证，也请设置 PHOENIX_API_KEY。

3. 运行 MCP 客户端。客户端代码会在运行时于单独进程中启动服务端。

   python client.py
   

4. 向 Agent 提问。

5. 在 Phoenix 中查看追踪：

工作原理

openinference-instrumentation-mcp 软件包会自动：

1. 为 MCP 客户端操作创建 span
2. 将跟踪上下文注入 MCP 请求
3. 在服务端提取并延续跟踪上下文
4. 将上下文与服务端创建的任何 OTEL span 关联起来

这样，即使请求流跨越了服务边界，你也能将其作为一条完整的跟踪记录查看。