MCP server (/api/public/mcp) exposes no trace/session read or tag-write tools, despite docs claiming it can “inspect traces”

快速结论：此报错表明 Langfuse 自带的 MCP 服务器目前缺少针对 traces/sessions 的读取和标签写入工具（如 listTraces、getTrace），而官方文档声称支持 “inspect traces” 但实际工具列表中并未包含这些功能。优先排查你所使用的 Langfuse 版本是否支持 v4 数据模型，或考虑使用 Langfuse CLI 替代 MCP 服务器。

问题场景

用户在自部署的 Langfuse 3.208.0 版本中，通过 HTTP 传输协议将 MCP 端点 /api/public/mcp 注册到 Claude Code 客户端（使用 Authorization: Basic <base64(public_key:secret_key)> 认证方式），连接成功后枚举可用工具列表时发现缺少 trace/session 相关工具。

报错原文

The full tool list returned by the connected server is:

createAnnotationQueue, createAnnotationQueueAssignment, createAnnotationQueueItem,
createChatPrompt, createComment, createDashboardWidget, createDatasetRunItem,
createEvaluationRule, createModel, createScore, createScoreConfig, createTextPrompt,
deleteAnnotationQueueAssignment, deleteAnnotationQueueItem, deleteDatasetItem,
deleteDatasetRun, deleteEvaluationRule, deleteEvaluator, deleteModel,
deleteScoreConfig, getAnnotationQueue, getAnnotationQueueItem, getComment,
getDataset, getDatasetItem, getDatasetRun, getEvaluationRule, getEvaluator,
getHealth, getMedia, getModel, getPrompt, getPromptUnresolved, getScore,
getScoreConfig, listAnnotationQueueItems, listAnnotationQueues, listComments,
listDatasetItems, listDatasetRunItems, listDatasetRuns, listDatasets,
listEvaluationRules, listEvaluators, listModels, listPrompts, listScoreConfigs,
listScores, updateAnnotationQueueItem, updateEvaluationRule, updatePromptLabels,
updateScoreConfig, upsertDataset, upsertDatasetItem, upsertEvaluator

Notably absent: anything for traces or sessions as first-class objects — no listing, no reading, no tag mutation.

原因分析

这是 Langfuse MCP 服务器的一个已知功能缺口。根据 Langfuse 团队的回应，trace 支持已在路线图上但暂无具体时间表。官方文档中 “inspect traces” 的能力可能指的是 2026 年 5 月 MCP 更新中添加的 Observations 和 Metrics 工具，但这些工具需要 v4 数据模型，而自部署版本尚未支持此模型。因此，当前所有部署（包括云版和自部署版）的 MCP 工具表面都未包含 traces/sessions 的读取/写入工具。

环境排查

确认 Langfuse 版本（运行 getHealth 确认版本号，例如 3.208.0）
确认是否使用的是自部署版本（self-hosted），云版是否有差异
确认 MCP 端点是否使用正确的 HTTP 传输协议和认证方式
检查是否已尝试使用 Langfuse CLI 作为替代方案

解决步骤

确认问题性质：这不是配置错误或连接问题，而是 MCP 服务器工具表面的设计缺失。运行 claude mcp list 或通过 MCP 客户端枚举工具列表，验证是否确实缺少 trace/session 相关工具。
替代方案（可优先尝试）：Langfuse 团队推荐使用 Langfuse CLI 替代 MCP 服务器进行 trace/session 操作。CLI 封装了完整的 REST API，支持 trace/session 检索，可以作为工具/技能安装在 Claude Code 或类似代理中。
安装 Langfuse CLI：参考官方文档 https://langfuse.com/docs/api-and-data-platform/features/cli，按照说明安装并配置 CLI。
配置 Claude Code 使用 CLI：将 Langfuse CLI 注册为 Claude Code 的工具/技能，以便代理可以直接调用 trace/session 相关命令。
等待官方更新：关注 Langfuse MCP 服务器的更新日志（https://langfuse.com/changelog）和 GitHub 讨论（https://github.com/orgs/langfuse/discussions/10605），等待 v4 数据模型和 trace/session MCP 工具的正式发布。

验证方法

通过 Langfuse CLI 执行 trace 查询命令（例如 langfuse trace list 或类似命令），确认可以成功列出和读取 trace 数据。如果使用 MCP 服务器，可以暂时接受现状，通过 createComment 工具间接操作 trace/session（虽然功能有限），或等待官方更新。