{"$schema":"https://wellknown.network/schemas/agent-record-v1.json","schemaVersion":"1","id":"ag_c2skq5xsjv2b","handle":"langfuse-trace-mcp","url":"https://wellknown.network/agents/langfuse-trace-mcp","links":{"self":"https://wellknown.network/agents/langfuse-trace-mcp/record.json","html":"https://wellknown.network/agents/langfuse-trace-mcp","markdown":"https://wellknown.network/agents/langfuse-trace-mcp/record.md","api":"https://wellknown.network/api/v1/agents/langfuse-trace-mcp","status":"https://wellknown.network/api/v1/agents/langfuse-trace-mcp/status","claim":"https://wellknown.network/agents/langfuse-trace-mcp/claim","claimApi":"https://wellknown.network/api/v1/claims","claimDescriptor":"https://wellknown.network/agents/langfuse-trace-mcp/claim.json","badge":"https://wellknown.network/agents/langfuse-trace-mcp/badge.svg","openapi":"https://wellknown.network/openapi.json","history":"https://wellknown.network/api/v1/agents/langfuse-trace-mcp/history","tools":"https://wellknown.network/api/v1/agents/langfuse-trace-mcp/tools"},"ard":{"identifier":"urn:air::server:langfuse-trace-mcp","type":"application/mcp-server-card+json"},"kind":"mcp_server","declared":{"name":"langfuse-trace-mcp","summary":"Read-only stdio MCP server for Langfuse traces","description":"# langfuse-trace-mcp\n\n用于分析 Langfuse Trace、Session 和 badcase 的只读 Python MCP 服务，通过 stdio 提供六个工具。服务负责查询、分页和正文切片，分析由 Codex、Claude 等调用方完成；工具内部不调用大模型。\n\n支持按 Trace ID、Session ID 或时间范围查询，先返回摘要，再按需分页读取节点和正文，减少一次查询带来的 token 消耗。\n\nPython 分发包名为 `langfuse-trace-mcp`，命令行入口为 `langfuse-mcp`，Python 模块名为 `langfuse_mcp`。\n\n## 1. 从 PyPI 安装\n\n准备好以下内容：\n\n- [uv](https://docs.astral.sh/uv/getting-started/installation/)（包含 `uvx`）。已有 uv 时无需重新安装。\n- 运行客户端的机器能够下载 PyPI 依赖，并访问 Langfuse。\n- 同一个 Langfuse 项目的 Public Key 和 Secret Key，可从该项目的 API Keys 设置中获取。\n\n在任意目录执行以下命令，从 [PyPI](https://pypi.org/project/langfuse-trace-mcp/) 安装并检查启动入口：\n\n```bash\nuvx --python 3.12 \\\n  --from langfuse-trace-mcp==0.1.0.post1 \\\n  langfuse-mcp --help\n```\n\n`uvx` 首次运行时会自动创建隔离环境、安装包及其依赖，后续复用缓存。`--python 3.12` 指定运行时；本机缺少该版本时，uv 默认会自动下载。运行依赖包含官方 MCP Python SDK 和 httpx，服务直接调用 Langfuse Public API。\n\n正常输出应包含 `--base-url`、`--public-key`、`--secret-key` 三个参数。这个检查只启动命令行帮助，不连接 Langfuse。\n\n包名与命令名不同：`--from langfuse-trace-mcp==0.1.0.post1` 指定安装来源，后面的 `langfuse-mcp` 是执行入口。客户端配置中也需要保留这一组合。\n\n以下示例固定使用 `0.1.0.post1`。升级时，将配置中的版本号改为已发布的新版本，先运行对应版本的 `--help` 完成安装，再重启客户端。\n\n## 2. 在客户端中配置\n\n服务通过 **stdio** 通信，由客户端自动启动和管理进程，无需先手动启动或使用 `nohup` 常驻后台。它不提供可填写到远程 MCP 连接框的 HTTP 地址。\n\n所有客户端使用相同的三个启动参数：\n\n| 参数 | 填写内容 |\n| --- | --- |\n| `--base-url` | Langfuse 服务地址，如 `https://langfuse.example.com`；不要追加 `/api/public` |\n| `--public-key` | Langfuse 项目的 Public Key |\n| `--secret-key` | 同一项目的 Secret Key |\n\n下面的地址和密钥都是占位符，使用前请替换。连接凭据在启动时传入，工具调用中无需传入凭据或 `environment`。\n\n配置中的 `command` 使用 `uvx`。如果桌面客户端找不到它，请查出实际路径，并将 `command` 改为该绝对路径：\n\n| 系统 | 查找 uvx 的命令 |\n| --- | --- |\n| macOS / Linux | `command -v uvx` |\n| Windows PowerShell | `(Get-Command uvx).Source` |\n\nWindows 的 JSON / TOML 配置中可用 `/` 表示路径分隔符，例如 `C:/Users/你的用户名/.local/bin/uvx.exe`。\n\n### Codex 桌面客户端 / CLI\n\n打开 `~/.codex/config.toml`，添加以下配置；若已有 `[mcp_servers.langfuse]`，修改原条目即可：\n\n```toml\n[mcp_servers.langfuse]\ncommand = \"uvx\"\nargs = [\n  \"--python\", \"3.12\",\n  \"--from\", \"langfuse-trace-mcp==0.1.0.post1\",\n  \"langfuse-mcp\",\n  \"--base-u…","publisher":null,"homepage":null,"repository":null,"version":"0.1.0.post1","license":null,"protocols":["mcp"],"tags":["langfuse","mcp","observability","traces"],"pricing":null,"endpoints":[{"url":"pypi:langfuse-trace-mcp","type":"package_pypi","auth":null,"probeable":false}],"skills":null,"tools":null,"extra":null,"attribution":{"kind":"pypi","name":"pypi","summary":"pypi","version":"pypi","description":"pypi"}},"derived":{"capabilities":[{"slug":"dev.monitoring","name":"Monitoring & Observability","confidence":1,"provenance":"declared"}],"categories":["dev"],"language":"en"},"observed":{"status":"unknown","statusReason":"Distributed as a package to run locally; no network endpoint to check.","lastOkAt":null,"lastProbedAt":null,"statusComputedAt":null,"reliability30d":null,"latestObservations":[],"tools":null,"package":{"name":"langfuse-trace-mcp","registry":"pypi","observedAt":"2026-11-05T21:26:47.930Z","publishedAt":"2026-10-10T10:39:55.117974Z","latestVersion":"0.1.0.post1"},"toolSurface":null,"endpointFacts":[]},"verification":{"claimed":false,"claimedAt":null,"proofs":[]},"provenance":{"sources":[{"source":"pypi","key":"langfuse-trace-mcp","url":"https://pypi.org/project/langfuse-trace-mcp/","firstSeenAt":"2026-10-12T14:24:51.178Z","fetchedAt":"2026-11-05T21:26:06.928Z","normalizedAt":"2026-11-05T21:26:06.928Z"}]},"firstSeenAt":"2026-10-12T14:24:51.178Z","updatedAt":"2026-11-05T21:26:47.930Z"}