Langfuse Observability MCP

langfuse-observability-mcp 是一个只读 MCP Server，让 Codex、Claude Code、 Claude Agent SDK 等 Agent 能够渐进式查询和分析 Langfuse 中的可观测数据。 本项目的首要兼容目标是 Langfuse Self-hosted v3.175.0。

Agent -> MCP Tools -> Services -> LangfuseQueryClient -> V3 Adapter
      -> Langfuse 官方 Python SDK -> Langfuse v3.175.0

项目将能力分为两层：

• SDK 等价查询：Trace、Session、Observation、Score 和 Metrics 查询。
• Agent 分析：Trace Tree、Trace/Session Summary、错误节点、慢节点、Token/Cost 聚合。

MCP Tools 和 Services 不直接导入 SDK 生成代码，只有 compat/v3.py 了解具体 SDK Namespace。未来升级 Langfuse v4 时可以新增 compat/v4.py，而不修改 Tool 和分析逻辑。

版本选择与兼容性研究

实现已对照以下源码：

• Langfuse Server v3.175.0 Tag
• Langfuse 官方 Python SDK v3.15.0 Tag

两个版本均发布于 2026-05-21。SDK 3.15.0 提供本项目需要的 v3 查询接口， 因此项目固定使用该版本，避免意外切换到 v4-first API。

Langfuse Server v3.175.0 已确认提供：

• /api/public/traces 和 /api/public/traces/{id}
• /api/public/sessions 和 /api/public/sessions/{id}
• /api/public/observations 和 /api/public/observations/{id}（v1）
• /api/public/v2/scores
• /api/public/metrics（v1/Legacy）

虽然该服务端版本中已经出现 Observations v2 和 Metrics v2，但当前项目不使用它们。 稳定的 v1 接口已经覆盖当前需求，也能避免 MCP 契约过早绑定 v4 的 observations-first 和 Cursor Pagination 语义。

依赖版本：

• Python >=3.11
• Langfuse 官方 Python SDK langfuse==3.15.0
• MCP 官方 Python SDK mcp>=1.27,<2，当前锁定为 1.28.1
• MCP Transport：Streamable HTTP

安装与运行

需要安装 Python 3.11+ 和 uv。

cp .env.example .env
make install
make run

默认监听地址：

http://0.0.0.0:8000/mcp

本机客户端应连接：

http://127.0.0.1:8000/mcp

make run 会在启动前清除继承的 ALL_PROXY、HTTP_PROXY 和 HTTPS_PROXY 环境变量，使 Langfuse 官方 SDK 直接连接远端实例，不依赖 socksio。

配置

使用 Langfuse Project API Key：

LANGFUSE_PUBLIC_KEY=pk-lf-xxx
LANGFUSE_SECRET_KEY=sk-lf-xxx
LANGFUSE_BASE_URL=https://langfuse.example.com

LOG_LEVEL=INFO

MCP_HOST=0.0.0.0
MCP_PORT=8000
MCP_PATH=/mcp

Secret 和 Authorization Header 不会被记录或通过 MCP 返回。日志只包含 Tool 名称、 安全的 ID/Filter、查询耗时、返回数量、分页信息和错误，不记录完整 Input/Output。

跨域默认全部开放，无需配置环境变量。服务返回 Access-Control-Allow-Origin: *， 允许所有 Method 和 Header，并向浏览器暴露 Mcp-Session-Id 响应头。

Host Header 默认不做白名单限制，也无需配置 MCP_ALLOWED_HOSTS。公网部署时应由 反向代理负责 Host 校验、TLS 和身份认证。

本项目当前没有额外实现 MCP 身份认证。部署到非私有网络时，应放在带 TLS 和认证的 反向代理后面，不要直接把 8000 端口暴露到公网。

MCP 客户端配置

Codex 的 ~/.codex/config.toml：

[mcp_servers.langfuse-observability]
url = "http://127.0.0.1:8000/mcp"

Claude Code：

claude mcp add --transport http \
  langfuse-observability http://127.0.0.1:8000/mcp

Claude Agent SDK 使用相同的 Streamable HTTP URL。

Docker 与 Kubernetes

构建并运行：

make docker-build
make docker-run

等价命令：

docker build -t langfuse-observability-mcp:local .
docker run --rm \
  --name langfuse-observability-mcp \
  --env-file .env \
  -p 8000:8000 \
  langfuse-observability-mcp:local

容器以 UID 10001 的非 root 用户运行，监听 0.0.0.0:8000，健康检查通过 TCP 连接探测 MCP 端口。Docker 构建不依赖 uv 基础镜像，而是在 Python 基础镜像中通过 清华 PyPI 镜像安装固定版本 uv==0.11.8。镜像内置以下 Pod 排障工具：

curl, dig, nslookup, ip, ping, ss, nc, ps, top, jq, less, vi

进入运行中的 Pod：

kubectl exec -it <pod-name> -- bash

常用检查：

curl -i http://127.0.0.1:8000/mcp
ss -lntp
dig <langfuse-domain>
nc -vz <langfuse-host> 443
ps aux

.dockerignore 会排除 .env、Git 数据、虚拟环境和缓存，真实 Key 只能通过运行时 环境变量或 Kubernetes Secret 注入，不会写入镜像。

可用 Tools

Tool	用途
get_trace	按 ID 查询 Trace，支持 compact/standard/full 字段裁剪
list_traces	使用 Langfuse v3 原生 Filter 和 Pagination 查询 Trace
get_trace_summary	Trace 时长、错误、告警、Token、Cost 和慢节点摘要
get_trace_tree	构建有界 Trace Forest，处理多 Root、Orphan 和 Cycle
get_session	查询 Session 及其 Trace 引用
list_sessions	使用 v3 原生参数分页查询 Session
get_session_summary	Session 级 Trace、Observation、错误、Token 和 Cost 摘要
get_session_trace_list	分页获取 Session 下的紧凑 Trace 列表
get_observation	查询单个 Observation，Input/Output 默认不返回
list_observations	Observation v1 查询，以及派生的 Session 查询
get_error_observations	查询 ERROR、WARNING 或带 Status Message 的节点
get_slow_observations	按 Duration 倒序查询慢节点
list_scores	使用 v3.175.0 支持的 Score API v2 查询评分
query_metrics	使用 Metrics API v1/Legacy 查询指标

Query Tool 参数

所有 List Tool 保留原生 page + limit 分页，并补充：

pagination.has_more
pagination.next_page

list_traces

page, limit, user_id, name, session_id,
from_timestamp, to_timestamp, order_by, tags,
version, release, environment, fields,
raw_filter, detail_level

list_sessions

page, limit, from_timestamp, to_timestamp, environment

list_observations

page, limit, trace_id, session_id, user_id, name,
type, level, parent_observation_id,
from_start_time, to_start_time,
version, environment, raw_filter, detail_level

Observation v1 没有原生 session_id Filter。项目会严格通过官方 SDK 执行：

按 Session 查询 Trace
-> 获取 Trace IDs
-> 分页查询各 Trace 的 v1 Observations
-> 合并并应用 MCP 分页

不会绕过 SDK 手写 REST Client。

list_scores

page, limit, trace_id, observation_id, session_id,
user_id, name, source, value, operator,
from_timestamp, to_timestamp, environment,
score_ids, config_id, queue_id, data_type,
trace_tags, fields

query_metrics

接收官方 Metrics v1 Query Object：

view, dimensions, metrics, filters,
timeDimension, fromTimestamp, toTimestamp,
orderBy, config

raw_filter 是 Langfuse 官方 Filter 数组，元素包含 type、column、operator、 value 和可选的 key。提供 raw_filter 时，它优先于对应的简单参数。

字段裁剪规则：

• compact：移除 Input、Output、Metadata。
• standard：移除 Input、Output。
• full：保留 SDK 返回字段。
• get_observation(include_io=true)：显式返回 Input/Output。

Agent 渐进式分析示例

分析慢 Session：

get_session_summary(session_id)
-> get_session_trace_list(session_id)
-> get_trace_summary(trace_id)
-> get_trace_tree(trace_id)
-> get_slow_observations(trace_id=...)
-> 仅在必要时 get_observation(observation_id, include_io=true)

查询用户最近的失败请求：

list_traces(
    user_id="user-123",
    from_timestamp="...",
    order_by="timestamp.desc"
)
-> get_trace_summary(trace_id)
-> get_error_observations(trace_id=...)
-> get_observation(observation_id)

Langfuse v3.175.0 Compatibility Matrix

以下能力已核对源码和官方 SDK，并于 2026-07-22 在配置的真实 Langfuse v3.175.0 实例上完成运行验证。

Capability	v3.175.0 状态	官方 SDK 3.15.0 Namespace/Method
Authentication	运行验证通过	Langfuse(public_key, secret_key, base_url)
get_trace	运行验证通过	async_api.trace.get
list_traces	运行验证通过	async_api.trace.list
get_session	运行验证通过	async_api.sessions.get
list_sessions	运行验证通过	async_api.sessions.list
get_observation	运行验证通过，v1	async_api.observations.get
list_observations	运行验证通过，v1	async_api.observations.get_many
list_scores	运行验证通过，Score v2	async_api.score_v_2.get
query_metrics	运行验证通过，Legacy/Limited	async_api.metrics.metrics（v1）

Metrics 明确限制为 v1 Query Model 及其 View/Measure，不调用 Metrics v2。

测试与质量检查

make test
make test-unit
make test-integration
make lint
make typecheck
make check

真实兼容测试默认跳过。执行方式：

LANGFUSE_COMPAT_TEST=1 \
LANGFUSE_EXPECTED_SERVER_VERSION=3.175.0 \
LANGFUSE_PUBLIC_KEY=pk-lf-... \
LANGFUSE_SECRET_KEY=sk-lf-... \
LANGFUSE_BASE_URL=https://langfuse.example.com \
make test-compat

LANGFUSE_EXPECTED_SERVER_VERSION 是显式保护，避免误将其他版本的部署认证为 v3.175.0。

Unit Test 覆盖：

• Trace Tree
• 2000+ Observation
• Cycle Parent
• Orphan Node
• Pagination
• Query Filter Mapping
• Detail Level 和 Input/Output 裁剪
• Session Summary
• Error/Slow Observation

Integration Test 验证官方 SDK 的 Generated Client Namespace 和 Method 签名。 Compatibility Test 验证真实 Langfuse v3.175.0 实例。

已知限制

• 分析聚合最多采集 10,000 条 Trace/Observation，达到上限时返回 truncated=true。
• Session Observation 查询可能产生较多官方 SDK 请求，大型 Session 应先使用 Summary， 再缩小到具体 Trace。
• Trace Tree 会限制 Depth 和 Children，并返回省略数量。
• Metrics 仅使用 v1，不暴露 Metrics v2-only View 或 Measure。
• Observation v1 使用 Page Pagination，没有 Fields Selection 和原生 Session Filter。
• get_session 的 Trace 由后端不分页返回；大型 Session 推荐使用 get_session_summary 和 get_session_trace_list。

Langfuse v4 升级路径

升级时新增 compat/v4.py，实现相同的 LangfuseQueryAdapter，并在 Client 构造阶段 切换 Adapter，然后更新 Compatibility Test 和 Matrix。

届时 v4 Adapter 可以使用：

• Observations API v2
• Metrics API v2
• Cursor Pagination
• 原生 Fields Selection

MCP Tools、Services、Agent 调用语义和分析算法无需修改。

Makefile 命令

make install
make run
make docker-build
make docker-run
make test
make test-unit
make test-integration
make test-compat
make lint
make format
make typecheck
make check
make clean

项目仅使用 uv 管理依赖，不维护 requirements.txt。 项目级 uv 默认索引已配置为清华 PyPI 镜像：

https://pypi.tuna.tsinghua.edu.cn/simple