MCP LangFuse self-hosted issue

快速结论：在自托管 LangFuse v3.187.0 上使用 MCP 工具时，listObservations、getObservation、queryMetrics 等核心工具缺失。优先检查是否已迁移至 LangFuse v4，这些 MCP 工具仅在 v4 中可用。

问题场景

用户运行自托管 LangFuse 服务（版本 3.187.0），通过 MCP 协议调用工具时，发现 Observations 和 Metrics 两个类别下的 MCP 工具完全缺失。用户已确认其他类别工具（如 Prompts、Scores、Datasets 等）均正常工作。

报错原文

❌ Missing:
listObservations
getObservation
getObservationFieldSchema
getObservationFilterSchema
getObservationFilterValues
getMetricsSchema
queryMetrics

原因分析

根据 LangFuse 官方开发者在 Issue 中确认：缺失的 MCP 工具（Observations 和 Metrics 类别）仅在 LangFuse v4 中可用。用户当前运行的 v3.187.0 虽然版本号较新，但尚未包含这些工具。即使从零搭建新部署，也必须迁移到 v4 架构才能使用上述 MCP 工具。

此外，v4 还要求显式启用 opt-in 环境变量 LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN，且必须使用 Python v4 SDK 或 JavaScript v5 SDK（或基于 OpenTelemetry 的外部埋点方案）。

环境排查

LangFuse 版本：确认当前 LangFuse 版本（GET /api/public/health 返回 version 字段）
MCP 工具列表：通过工具发现接口确认 Observations 和 Metrics 是否已注册
v4 启用标志：检查是否有设置 LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN 环境变量（非强制但建议确认）
数据迁移状态：如果你已有现存数据，需要关注 v4 数据迁移是否已完成；若从零搭建则无需迁移
SDK 版本：如果你通过代码调用 MCP 接口，确认使用的 LangFuse SDK 是 Python v4 或 JavaScript v5

解决步骤

确认是否必须升级到 v4：阅读 LangFuse v4 官方文档 langfuse.com/docs/v4，了解 v4 引入的架构变化。
从零搭建新部署（可丢弃现有数据）：
- 按照 GitHub Discussion #14157 中的指引设置 v4 自托管实例。
- 启用 v4 preview opt-in：LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN=true（可优先尝试）
- 确保使用 Python v4 SDK 或 JavaScript v5 SDK 或基于 OpenTelemetry 的埋点方案。
如果已有数据需要保留：
- 等待 LangFuse 团队完成 v4 数据迁移工具/流程。
- 订阅 Discussion #12518 获取迁移进度更新。
验证配置：重启 LangFuse 服务后，重新调用 MCP 工具发现接口，检查 listObservations 和 queryMetrics 是否已出现。

验证方法

重启服务后，通过 MCP 客户端或 curl 调用工具发现列表，确认 listObservations、getObservation、getMetricsSchema、queryMetrics 等工具已出现在可用列表中。也可执行一次简单的 listObservations 操作，确认能正常返回数据。