LLM可观测性服务器

Langfuse MCP服务器

模型上下文协议 服务器 浪焰 可观察性。查询跟踪、分析准确性、检测故障、跟踪成本、调试延迟、管理提示和数据集。

56工具 跨数据访问和分析。多项目支持，因此一个实例可以服务于多个Langfuse项目。适用于 克劳德代码, Codex CLI, 光标，以及任何兼容MCP的客户端。

为什么选择MCP服务器？

对比 廊坊MCP官方 （截至2026年3月）：

官方MCP专注于快速管理。此服务器提供 完整的可观察性和分析工具包 --跟踪、观察、会话、分数、异常、提示、数据集、注释队列，以及9个内置分析工具，这些工具在服务器端计算洞察并返回LLM大小的摘要。多项目路由允许单个实例在一个连接器URL后面为多个Langfuse项目提供服务。

快速开始

1.获取API密钥

• 廊坊云： cloud.langfuse.com → 设置→ API密钥
• 自托管： 您的Langfuse实例→ 设置→ API密钥。集 LANGFUSE_HOST 到您的实例URL（例如。， https://langfuse.yourcompany.com)

2.添加MCP服务器

克劳德代码

claude mcp add \
  -e LANGFUSE_PUBLIC_KEY=pk-lf-... \
  -e LANGFUSE_SECRET_KEY=sk-lf-... \
  -e LANGFUSE_HOST=https://cloud.langfuse.com \
  --scope project \
  langfuse-mcp -- uvx langfuse-mcp-server

Codex CLI

codex mcp add langfuse-mcp \
  --env LANGFUSE_PUBLIC_KEY=pk-lf-... \
  --env LANGFUSE_SECRET_KEY=sk-lf-... \
  --env LANGFUSE_HOST=https://cloud.langfuse.com \
  -- uvx langfuse-mcp-server

光标

添加 .cursor/mcp.json:

{
  "mcpServers": {
    "langfuse-mcp": {
      "command": "uvx",
      "args": ["langfuse-mcp-server"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-...",
        "LANGFUSE_SECRET_KEY": "sk-lf-...",
        "LANGFUSE_HOST": "https://cloud.langfuse.com"
      }
    }
  }
}

3.验证

重新启动CLI，然后使用进行测试 /mcp （克劳德代码）或 codex mcp list （食品法典委员会）。

手动安装（uvx的替代品）

pip install langfuse-mcp-server
langfuse-mcp-server

作为远程服务托管

作为长期HTTP服务运行，以便多个用户连接到单个实例——这是 Claude.ai定制连接器，并且可用于在不向每个用户分发Langfuse API密钥的情况下进行团队访问。

通过env变量启用；没有代码更改。

最低设置

MCP_TRANSPORT=streamable-http
MCP_BASE_URL=https://mcp.yourcompany.com
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://your-langfuse-instance.example

如果没有OAuth环境变量，端点将无法通过身份验证，仅适用于本地测试。请参阅下面的Google OAuth设置以获取生产信息。

码头工人

生产准备就绪 Dockerfile 被签入仓库（非root用户、固定基座、非root用户）， .dockerignore 以防止秘密泄露）。每个标记的版本都会通过以下方式自动将多拱形映像发布到GitHub容器注册表 .github/workflows/docker-publish.yml.

拉取已发布的图像：

docker pull ghcr.io/drishtantkaushal/langfusemcp:latest

或者从源代码构建：

docker build -t langfuse-mcp .

运行（所有秘密通过注入 -e，从未融入图像中）：

docker run -d \
  --name langfuse-mcp \
  --restart unless-stopped \
  -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_BASE_URL=https://mcp.yourcompany.com \
  -e LANGFUSE_PUBLIC_KEY=pk-lf-... \
  -e LANGFUSE_SECRET_KEY=sk-lf-... \
  -e LANGFUSE_HOST=https://cloud.langfuse.com \
  -e GOOGLE_CLIENT_ID=... \
  -e GOOGLE_CLIENT_SECRET=... \
  -e ALLOWED_EMAIL_DOMAINS=yourcompany.com \
  ghcr.io/drishtantkaushal/langfusemcp:latest

反向代理

在前面终止TLS（nginx、Caddy、Cloudflare）。MCP端点位于 /mcp/ （尾随斜线）。由于响应流，代理必须：

• 禁用响应缓冲 --nginx： proxy_buffering off;
• 允许读取超时≥5分钟 --一些分析查询可以合法地运行几分钟
• 使用keepalive上游讲HTTP/1.1

谷歌OAuth

在您的Google Cloud项目中：

1. API和服务→ OAuth 同意屏幕
   • 用户类型： 内部 （限制登录您的Google Workspace域）
   • 范围： openid, https://www.googleapis.com/auth/userinfo.email
2. 凭证→ 创建OAuth客户端ID→ 网络应用程序
   • 授权重定向URI： https://{your-base-url}/auth/callback
   • 复制客户端ID和客户端密码

设置：

GOOGLE_CLIENT_ID=....apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-...

OAuth在以下情况下激活 GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET，以及 MCP_BASE_URL 都准备好了。通过内部同意屏幕，谷歌在身份层拒绝非工作区登录——服务器永远不会看到这些尝试。

可选电子邮件列表

对于比“工作区中的任何人”更窄的控制：

# either, or both
ALLOWED_EMAIL_DOMAINS=yourcompany.com
ALLOWED_EMAILS=alice@yourcompany.com,bob@yourcompany.com

设置后，每次工具调用都会验证调用者的 email_verified 在继续之前，要求并检查会员资格。当未设置时，服务器信任OAuth提供者返回的任何内容。

添加到Claude.ai

一旦托管在 https://mcp.yourcompany.com:

1. Claude.ai→ 设置→ 连接器→ 添加自定义连接器
2. 远程MCP服务器URL: https://mcp.yourcompany.com/mcp/
3. 将OAuth客户端ID/密钥字段留空 --服务器使用动态客户端注册；这些字段用于不同的部署模式。
4. 点击添加→ 谷歌登录弹出窗口→ done.

验证部署

已启用身份验证，预计401：

curl -i -X POST https://mcp.yourcompany.com/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

OAuth元数据端点返回JSON（Claude.ai用于自动注册）：

curl https://mcp.yourcompany.com/.well-known/oauth-authorization-server

活体/准备状态探测——未经验证 GET /health 返回HTTP 200 {"status": "ok"}，适用于Kubernetes探测器：

curl -i https://mcp.yourcompany.com/health

多项目支持

单个服务器实例可以路由到多个Langfuse项目。每个工具都接受一个可选 project 论证；如果省略，则使用服务器配置的默认值。呼叫 list_projects 以发现可用的内容。

配置工程

通过索引的env变量声明每个项目。项目名称是数据，而不是变量名称的一部分——使用您喜欢的任何方案。

LANGFUSE_PROJECT_1_NAME=production
LANGFUSE_PROJECT_1_PUBLIC_KEY=pk-lf-...
LANGFUSE_PROJECT_1_SECRET_KEY=sk-lf-...
LANGFUSE_PROJECT_1_HOST=https://cloud.langfuse.com

LANGFUSE_PROJECT_2_NAME=staging
LANGFUSE_PROJECT_2_PUBLIC_KEY=pk-lf-...
LANGFUSE_PROJECT_2_SECRET_KEY=sk-lf-...
LANGFUSE_PROJECT_2_HOST=https://cloud.langfuse.com

LANGFUSE_DEFAULT_PROJECT=production

客户端使用

Claude: "Show me failing traces in production today."
→ fetch_traces(project="production", ...) routed to project 1's credentials.

Claude: "Compare that with staging."
→ fetch_traces(project="staging", ...) routed to project 2's credentials.

每个项目都有自己的缓存、速率限制器和连接池。Claude.ai看到一个连接器；用户通过OAuth进行一次身份验证，可以查询会话中任何配置的项目。

单项目（遗留）模式

如果 LANGFUSE_PROJECT_1_NAME 如果未设置，服务器将回退到旧版 LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY / LANGFUSE_HOST var并将其注册为一个名为 default。现有部署保持不变。

配置

工具

分析（9个工具）

计算服务器端见解并返回简洁摘要的工具。这些超出了原始数据访问的范围——它们聚合、检测模式和计算统计数据，因此LLM可以在不达到上下文窗口限制的情况下对结果进行推理。

数据访问（25个工具）

完整的Langfuse API覆盖范围，用于查询和管理您的可观测性数据。

痕迹

观察

会话

错误

分数

提示

数据集

注释队列

指标

用户

评论

模型

项目

模式

例题

连接后，向您的AI助手提出以下问题：

代理商和管道健康状况

• “本周哪些代理人失败最多？”
• “按代理人姓名计算的失败率是多少？”
• “哪个代理的准确性最差？”
• “按微量显示前5名代理商”
• “是否有任何代理始终比其他代理慢？”
• 按准确性、延迟和成本比较所有代理

准确性和质量

• “我们本周的总体准确率是多少？”
• “过去30天每周的准确度趋势是什么？”
• “比较不同代理的准确性”
• “每日准确率细分是多少？”
• “哪些用户的准确度最差？”
• “有反馈分数的痕迹百分比是多少？”

故障与调试

• “给我看看今天的失败例子”
• “最常见的故障模式是什么？”
• “哪些用户看到的失败最多？”
• “代理人的失败率是多少？”
• “与上一周相比，本周的失败是增加还是减少？”
• “向我展示法学硕士说‘不能’或‘我不能’的痕迹”

令牌使用情况

• “P90和P99代币使用统计数据是什么？”
• “哪些代理消耗的代币最多？”
• “比较不同用户组的令牌使用情况”
• “是否有用户的代币数量异常高？”

上下文窗口违规

• “是否有任何一代人超过了128K的上下文窗口？”
• “显示每代令牌使用量超过20万的痕迹”
• “漏洞严重程度分布是什么？”
• “哪些用户触发的上下文窗口漏洞最多？”

会议和参与

• “我们的多回合率是多少？”
• “会话平均有多深？”
• “哪些用户的会话最深？”
• “本周有多少次单轮和多轮会议？”
• “平均会话成本是多少？”

成本

• “这周我们每天花多少钱？”
• “过去30天的每周成本趋势是什么？”
• “哪个代理最贵？”
• “哪些用户的成本最高？”
• “每条追踪的平均成本是多少？”

延迟

• “P95的延迟是多少？”
• “延迟是否会随着时间的推移而恶化？”
• “哪个型号最慢？”
• “比较代理之间的延迟”
• “按型号显示每代延迟细分”
• “哪些用户的延迟最高？”

注释和回写

• “用‘需求审查’对今天的所有失败痕迹进行评分”
• “将这些跟踪ID标记为数据集创建的‘高质量’”
• “将跟踪abc-123标记为0分，并评论‘幻觉输出’”

查找与探索

• “获取最后20条痕迹”
• “显示跟踪abc-123及其所有观测值”
• “列出用户的会话alice@example.com"
• “过去24小时发生了什么错误？”
• “本周发生了多少错误？”
• “显示项目中的所有提示”
• “列出所有数据集”
• “痕迹和观测中有哪些字段可用？”

分组选项

这 group_by 参数控制如何在分析工具中分割痕迹：

选择性工具加载

仅加载减少令牌开销所需的工具组：

# Only load traces and analytics tools
LANGFUSE_TOOLS=traces,analytics langfuse-mcp-server

# Only load prompts and datasets
LANGFUSE_TOOLS=prompts,datasets langfuse-mcp-server

# In Claude Code
claude mcp add \
  -e LANGFUSE_PUBLIC_KEY=pk-lf-... \
  -e LANGFUSE_SECRET_KEY=sk-lf-... \
  -e LANGFUSE_TOOLS=traces,observations,analytics \
  langfuse-mcp -- uvx langfuse-mcp-server

可用组：

如果 LANGFUSE_TOOLS 如果未设置，则加载了所有56个工具。

只读模式

禁用写入操作(score_traces, create_dataset, create_dataset_item, delete_dataset_item, create_text_prompt, create_chat_prompt):

LANGFUSE_MCP_READ_ONLY=true

如何比较

vs廊坊MCP官方

官方的Langfuse MCP（5个工具）侧重于快速管理。该服务器提供完整的可观察性覆盖以及9个分析工具。

与其他Langfuse MCP实现相比

其他实现使用同步HTTP客户端提供数据访问（获取原始跟踪、观察、会话）。此服务器添加了 计算层 --在服务器端聚合、检测模式和计算统计数据的分析工具，以及 异步架构 这基本上更快。

vs平台嵌入式人工智能（Braintrust Loop、LangSmith Insights、Arize Alyx）

建筑

为什么使用异步httpx而不是Langfuse SDK？

这 Langfuse Python SDK 非常适合 写作 跟踪（它在后台异步批处理和发送）。但为了 阅读 大规模跟踪——这就是分析MCP服务器所做的——SDK有一个局限性： 其读取的API是同步的，建立在 requests 图书馆。

此服务器使用 httpx.AsyncClient 相反，这使得：

• 并发观测获取 --通过以下方式同时获取100条记录的观测值 asyncio.gather，不是一个接一个
• 非阻塞分页 --在不阻塞事件循环的情况下对数千条跟踪进行分页
• 速率受限并发 — asyncio.Semaphore +令牌桶控制吞吐量，无需 time.sleep() 阻塞

实测影响： analyze_latency 在每天240万次观测的自托管实例上，每代故障从110秒下降到20秒（快5.4倍）。

缓存策略

使用两层内存TTL缓存 cachetools.TTLCache:

缓存在API页面级别运行。如果你打电话 aggregate_by_group 然后 compute_accuracy 对于相同的时间范围，第二次调用会访问所有跟踪页的缓存——只获取新的分数。

通过配置 LANGFUSE_CACHE_TTL 和 LANGFUSE_CACHE_TTL_HISTORICAL （秒）。

速率限制

全球代币桶利率限制器遵守Langfuse API限制：

在HTTP 429响应中，限制器会自动将RPM减半并读取 Retry-After 头球这意味着服务器可以适应任何速率限制——云或自托管——而无需手动配置。

观测数据获取：批处理与并发

需要生成数据（令牌百分比、上下文破坏、延迟崩溃）的分析工具面临N+1问题：每个跟踪一个API调用以获取其观察结果。

此服务器使用两步策略：

1. 尝试批量提取 --在内存中按traceId分组，在一次分页调用中获取时间范围内的所有观测值
2. 如果音量太大 （>5000页/500K+次观察）-- 回退到并发每次跟踪获取 使用 asyncio.gather 具有信号量控制的并发性

这意味着服务器既可以处理小型项目（批处理更快），也可以处理大规模部署（并发目标获取避免下载数百万个不相关的观测值）。

通过子代理进行上下文隔离

服务器随附 Claude Code定制代理 在 .claude/agents/langfuse-analyst.md当用户询问与Langfuse相关的问题时，Claude Code可以委托给该代理，该代理：

• 仅加载Langfuse MCP工具（不加载会话中的其他工具）
• 具有专门的系统提示，其中包含工具分类和工作流模式
• 在独立的上下文窗口中运行，保持主要对话的整洁
• 返回父对话的摘要

这可以防止33个工具模式（约5000个令牌）污染每次对话。

贡献

看 贡献.md 用于开发设置、代码风格指南和贡献领域。

安全

看 安全.md 用于安全策略、漏洞报告和API密钥处理。

行为准则

看 代码_OF_CONDUCT.md.

许可证

麻省理工学院——见 许可证.