Langfuse API

Name: Langfuse API
Author: rodrigorjsf

本地服务

github.com数据与分析02 周前更新

代码仓库访问官网

关于 Langfuse API

这是一款本地、无状态的 MCP 服务，让 AI Agent 通过 Langfuse 公共 API 检查和管理数据。它支持 Cloud、自托管部署及自定义 CA 证书；默认禁用写入。

主要功能

01检查 Trace 和 Trace 树
02读取提示词、数据集和指标
03发现部署支持的操作
04启用写入并逐次确认
05支持自定义 CA 证书

适用场景

01调查 Trace 错误、延迟和成本
02查看提示词、数据集或实验
03受控地修改 Langfuse 数据

MCP 相关

它通过本地服务向 MCP 客户端开放 Langfuse 公共 API 操作。默认提供读取；只有启用后才会出现写入工具，破坏性操作还需确认。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

暂未收录安装方式

我们还没有获取到这个服务的安装包或远程地址，请按项目 README 中的说明安装。

代码仓库

安装包

npmlangfuse-api-mcp0.2.0stdio

ocighcr.io/rodrigorjsf/langfuse-api-mcp:0.2.0stdio

mcpblangfuse-mcp_0.2.0.mcpbstdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

langfuse-api-mcp

一个 MCP 服务，可让 AI Agent 使用完整的 Langfuse 公共 API。它适用于任何区域的 Langfuse Cloud，也适用于可自托管实例。它专为运行在企业网络中而构建，这类网络会使用自己的证书颁发机构（CA）重新签署 TLS 流量。

重要

状态：预 Alpha，版本 v0.2.0（语义化版本 0.x：目前不承诺稳定性；首个版本为 v0.1.0）。除标注为计划中的内容（如环回 HTTP 传输）外，下文所述功能目前均可使用。

目录： 简介 · 工具 · 用户技能 · 安装和运行 · 客户端配置 · 配置 · 安全模型 · 故障排除 · 了解更多

简介

这是一个小型、无状态的程序，由你的 AI 工具（Claude Code、Claude Desktop、Cursor、VS Code、Codex 等）在本机启动。它使用 Model Context Protocol 与 Agent 通信，并通过 HTTPS 与 Langfuse 通信。这样，Agent 就可以：

调查追踪、观察记录、会话、错误、延迟和成本；
读取提示词、数据集、实验、评分、指标、模型、评论和标注队列；
进行更改，例如升级提示词标签、创建评分或编辑数据集。只有启用写入功能后才能执行这些操作（请参阅安全模型）。

flowchart LR
  A[AI agent<br/>Claude Code, Cursor, …] -- MCP over stdio --> S[langfuse-mcp<br/>on your machine or in Docker]
  S -- HTTPS + your corporate CA --> P{{Corporate proxy<br/>optional}}
  P --> L[(Langfuse<br/>Cloud or self-hosted)]
  S -. reads .-> C[/Your config:<br/>keys, host, CA files/]
  classDef local fill:#e0f2fe,stroke:#0369a1,color:#0c4a6e;
  classDef remote fill:#fef3c7,stroke:#b45309,color:#78350f;
  class A,S,C local;
  class L,P remote;

适用场景

情况	适合使用此服务吗？
公司网络使用自定义根 CA 检查 TLS，而官方 Langfuse MCP 或 CLI 因 `self-signed certificate in certificate chain` / `unable to get local issuer certificate` 而失败	适合。这正是本项目存在的主要原因。
你希望 Agent 无法更改 Langfuse 数据，除非你明确允许	适合。默认只读，并且此服务会对通过它发出的每次调用强制执行此限制。请勿将密钥放在 Agent 自身的环境中，否则其他工具可能会直接使用这些密钥：不要将密钥放在 Agent 的环境中。
你在内部 CA 或代理服务器后运行可自托管的 Langfuse	适合。
你希望使用单个二进制文件，且本机无需安装 Node.js 或 Python 运行时	适合。
你只需要 Agent 使用 Langfuse 文档	不适合。请使用官方文档 MCP：`https://langfuse.com/api/mcp`。
Agent 可以运行 Shell 命令，且你的网络没有 TLS 拦截	两种方式都可以。Langfuse 还提供官方 CLI 和 Agent Skill。

与官方 Langfuse MCP 的区别

	官方项目 MCP（`<host>/api/public/mcp`）	此服务
运行位置	远程，在 Langfuse 内部	本地（二进制文件或 Docker）
自定义 CA / 企业代理	取决于 MCP 客户端的运行时；没有文档说明相关配置选项	提供明确的设置，并会自动读取系统中已设置的 CA 环境变量
写入	默认启用；若要限制写入，需配置客户端允许列表	默认关闭。启用前，写入工具不会存在。
API 覆盖范围	精选工具集	Langfuse 部署实际支持的所有操作——较旧的可自托管版本保留其旧版 API，较新的版本使用新版 API——但不包括追踪数据写入和组织管理员更改（创建/删除项目、API 密钥和用户）。启动时自动检测，无需配置（部署配置）

工具

Langfuse API 约有 100 个符合范围的操作。每个操作对应一个工具会占满 Agent 的上下文窗口，因此该服务仅提供一小组工具：

工具	功能	可用性
`search_operations`	列出你的部署提供的 Langfuse 操作，可按关键词筛选（在写入模式下，还会列出每个写入操作的 HTTP 方法，以及该操作是否具有破坏性）	始终可用
`describe_operation`	返回你的部署所用 Langfuse 版本提供的某个操作的参数（此外，如果你的版本不支持某个筛选条件，还会返回服务自行应用的筛选条件；在写入模式下，还会返回请求体架构〔即你的部署所用 Langfuse 版本的架构〕、该操作是否具有破坏性，以及如何填写 `comments_create` 和 `scores_create` 的请求体）	始终可用
`execute_read`	按 ID 执行读取操作（HTTP GET），并在不可信数据封装中返回 Langfuse JSON。如果较旧版本的 Langfuse 忽略 `scores_get-many` 的 `traceId` 或 `legacy_observationsV1_getMany` 的 `level`，服务会自行应用该筛选条件，并说明是否读取了整个列表	始终可用
`execute_write`	按 ID 执行写入操作；破坏性操作（DELETE、PUT、PATCH）仅在你确认该确切调用后才会执行	仅在写入模式下可用
`get_trace_tree`	单次调用返回一条 trace 的所有 observation，并以树形结构呈现。部署能够响应 v4 读取 API（Cloud、自托管 v4）时，会读取 Observations v2；自托管 v3 则会读取旧版 observations 列表。除非你主动请求，否则不会返回 input、output 和 metadata；每一行包含 Langfuse 返回的字段（v4 中的延迟以秒为单位，此处以毫秒为单位），但会排除返回值为 null 的字段。如果部署能够响应这两种 API，则会从 Observations v2 读取树形结构；其中可能缺少通过旧版 ingestion API 发送的 observations，因此可以通过 `execute_read` 查询旧版 observations 列表，以核对空树或较短的树。如果这两种 API 均无响应，则会返回 `operation_unavailable`	始终列出；仅当部署能够响应任一 API 时运行

典型会话：search_operations 查找操作，describe_operation 显示其参数，execute_read 执行操作：

{"operationId": "trace_list", "parameters": {"limit": 10, "tags": ["prod", "checkout"]}}

该服务不会在调用之间保留任何内容（它是无状态的）。它绝不会接受 Agent 提供的 URL、主机或凭据。它只会针对你配置的主机，执行内置目录中的操作。每次调用在发送前都会经过验证，所有失败都会以结构化工具错误的形式返回，其中包含 code、hint 和 retryable 标记。参数、错误代码、结果上限和审计行：工具参考。

用户技能

该服务为 Agent 提供通用工具；用户技能 langfuse-api-mcp (skills/langfuse-api-mcp/) 会教它如何使用这些工具进行 Langfuse 调查：先发现，再描述，然后执行；始终限定时间范围；Langfuse 数据是不可信的，绝不是指令。它包含一个简短的入口文件，以及每种工作流各自的参考文档（跟踪、成本与延迟、提示词、实验、评分、错误），只有在请求相应工作流时才会加载。其描述列出了此服务的工具，因此不会与 Langfuse 自带的 langfuse 技能冲突。它本身不会增加任何权限：是否存在 execute_write，以及每次确认，都由服务决定。

Claude Code、Cursor、VS Code、Codex CLI、Gemini CLI、Windsurf。 使用 skills CLI 从仓库安装到项目中（或使用 -g 为当前用户安装）；--agent 用于指定要安装到的宿主（使用 --agent '*' 可安装到所有宿主）。Claude Code 的安装已验证；其他宿主则取决于 CLI 自身的支持：

npx skills add rodrigorjsf/langfuse-api-mcp
# non-interactive, one host: npx skills add rodrigorjsf/langfuse-api-mcp --agent claude-code -y

CLI 从 main 安装，而你的服务可能是较旧的版本；因此，该技能会指示 Agent 对所有未列出的参数调用 describe_operation（详情）。

Claude Desktop 仅支持通过上传安装技能。每个 GitHub 发布版本都附带一个经过签名的 langfuse-api-mcp-skill_<version>.zip，其根目录为 langfuse-api-mcp/ 文件夹；在 Claude Desktop 中，依次进入 Customize > Skills 并上传该文件。

安装和运行

渠道	平台	需要
npx	Linux、macOS、Windows × x64、arm64	带 npm 的 Node.js
发布归档	Linux、macOS、Windows × amd64、arm64	无
Docker	linux/amd64、linux/arm64；仅支持 stdio	Docker
Claude Desktop (MCPB)	macOS、Windows	Claude Desktop
`go install`	任意 Go 平台	Go 1.21 或更高版本

除 go install 外，所有渠道都经过签名或带有 npm 溯源信息：请参阅验证运行内容。该服务也已在 MCP Registry 中列出，名称为 io.github.rodrigorjsf/langfuse-api-mcp。各渠道的发布内容及构建方式：安装参考。

npx

在 MCP 客户端中将服务配置为 npx -y langfuse-api-mcp（使用 langfuse-api-mcp@<version> 固定版本）；它需要带 npm 的 Node.js，无需其他依赖。该软件包内含 Go 二进制文件：安装时不会下载任何内容，也不会运行安装脚本。请参阅客户端配置，查看客户端对应的代码片段。

发布归档

每个 GitHub 发布版本都包含各目标平台对应的一个归档文件：langfuse-mcp_<version>_<os>_<arch>.tar.gz（Windows 上为 .zip），以及 checksums.txt。使用 gh 或 curl 下载，对照 checksums.txt 检查归档文件，然后解压（以下示例为 Linux amd64；<version> 是不带前缀 v 的发布版本号，例如 0.2.0）：

version=<version>
archive="langfuse-mcp_${version}_linux_amd64.tar.gz"
gh release download "v$version" -R rodrigorjsf/langfuse-api-mcp -p "$archive" -p checksums.txt
# or: curl -fsSLO "https://github.com/rodrigorjsf/langfuse-api-mcp/releases/download/v$version/$archive"
#     curl -fsSLO "https://github.com/rodrigorjsf/langfuse-api-mcp/releases/download/v$version/checksums.txt"
awk -v f="$archive" '$2 == f' checksums.txt | sha256sum -c -   # macOS: … | shasum -a 256 -c -
tar -xzf "$archive"

在 Windows（PowerShell）上，对比哈希值并解压 zip 文件：

$archive = "langfuse-mcp_<version>_windows_amd64.zip"
(Get-FileHash $archive -Algorithm SHA256).Hash.ToLower()   # must equal the line for $archive in checksums.txt
Expand-Archive $archive -DestinationPath langfuse-mcp

然后将 MCP 客户端指向解压后的二进制文件（请参阅客户端配置）。这些二进制文件未经公证，也未通过 Authenticode 签名：请使用 curl 或 gh 下载，而不要使用浏览器；或者参阅通过浏览器下载？。

Docker

使用 -e 传入密钥和基础 URL，并保留 -i（服务通过 stdin 和 stdout 使用 MCP 通信）：

docker run -i --rm \
  -e LANGFUSE_PUBLIC_KEY -e LANGFUSE_SECRET_KEY -e LANGFUSE_BASE_URL \
  ghcr.io/rodrigorjsf/langfuse-api-mcp:<version>

不带值的 -e NAME 会从运行 docker 的环境中传入变量，因此密钥不会出现在命令行中。在企业 CA 环境下，以只读方式挂载 CA 文件，并将 LANGFUSE_CA_CERT 指向该文件；文件必须对任何用户都可读（镜像不会以你的身份运行）：

docker run -i --rm \
  -e LANGFUSE_PUBLIC_KEY -e LANGFUSE_SECRET_KEY -e LANGFUSE_BASE_URL \
  -e LANGFUSE_CA_CERT=/certs/corp.pem -v /path/to/corp.pem:/certs/corp.pem:ro \
  ghcr.io/rodrigorjsf/langfuse-api-mcp:<version>

在 MCP 客户端中，command 为 docker，args 为上面的列表；将密钥放在客户端的 env 块中，绝不要以 -e NAME=value 的形式放在 args 中。该镜像仅提供 stdio 服务。

Claude Desktop（MCPB）

从 GitHub release 下载 langfuse-mcp_<version>.mcpb（macOS、Windows amd64），然后双击它（或将其拖到 Claude Desktop 上）；安装对话框会要求填写：

字段	必填	对应变量
Langfuse 公钥	是；存储在 OS 钥匙串中，并以掩码显示	`LANGFUSE_PUBLIC_KEY`
Langfuse 秘钥	是；存储在 OS 钥匙串中，并以掩码显示	`LANGFUSE_SECRET_KEY`
Langfuse 基础 URL	是	`LANGFUSE_BASE_URL`
CA 证书	否；通过文件选择器指定	`LANGFUSE_CA_CERT`

对话框有意不提供写入模式选项：如需启用写入，请在配置文件中设置 LANGFUSE_MCP_ALLOW_WRITES=true。其他设置（代理、请求限制）也应放在配置文件中。

go install

安装某个发布版本（@v0.2.0 或 @latest）或某个提交（@main 或提交哈希）。需要 Go 1.21 或更高版本（模块的 toolchain 指令会获取所需的 Go 1.27 工具链）：

go install github.com/rodrigorjsf/langfuse-api-mcp/cmd/langfuse-mcp@<version>

二进制文件会放在 $(go env GOPATH)/bin 中。在检出目录中运行 go build -o langfuse-mcp ./cmd/langfuse-mcp 即可构建。

客户端配置

每种 MCP 客户端提供一个代码片段。所有片段都使用 npx 方式；若要改用发布归档，请将 "command": "npx", "args": ["-y", "langfuse-api-mcp"] 替换为 "command": "/absolute/path/to/langfuse-mcp"，且不设置 args（Windows 上使用 langfuse-mcp.exe）。

每个客户端都会根据自身的环境视图启动服务，而且有些客户端不会传递 shell 中的变量。因此，每个片段都通过客户端自身的 env 机制列出服务所需的三个变量；密钥只能放在这里。pk-lf-... 和 sk-lf-... 分别代表你的公钥和秘钥。若片段从客户端环境读取密钥（${VAR}、${env:NAME}、$NAME、env_vars），则需要在启动客户端的环境中导出密钥，Agent 自身的 shell 也会从那里继承密钥：请参阅让密钥远离 Agent 的环境。各客户端的所有注意事项和权衡详见：MCP 客户端详解。

Claude Code — 已验证

使用 --env 传入密钥；最后一个 --env 与服务名称之间必须放置一个选项（此处为 --transport stdio）。这样会将密钥存储在 ~/.claude.json 中：

claude mcp add \
  --env LANGFUSE_PUBLIC_KEY=pk-lf-... \
  --env LANGFUSE_SECRET_KEY=sk-lf-... \
  --env LANGFUSE_BASE_URL=https://cloud.langfuse.com \
  --transport stdio langfuse -- npx -y langfuse-api-mcp

对于项目的 .mcp.json，Claude Code 会在 env 中展开 ${VAR} 和 ${VAR:-default}：

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-api-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "${LANGFUSE_PUBLIC_KEY}",
        "LANGFUSE_SECRET_KEY": "${LANGFUSE_SECRET_KEY}",
        "LANGFUSE_BASE_URL": "${LANGFUSE_BASE_URL:-https://cloud.langfuse.com}"
      }
    }
  }
}

Claude Desktop

建议使用 MCPB 安装包，它会将密钥存储在 OS 钥匙串中。Claude Desktop 传递给服务的环境变量子集有限。若要手动配置，请编辑 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/；Windows：%APPDATA%\Claude\），将密钥放在 env 中，并将 command 设置为绝对路径（macOS 上运行 which npx，Windows 上运行 where npx）：

{
  "mcpServers": {
    "langfuse": {
      "command": "/absolute/path/to/npx",
      "args": ["-y", "langfuse-api-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-...",
        "LANGFUSE_SECRET_KEY": "sk-lf-...",
        "LANGFUSE_BASE_URL": "https://cloud.langfuse.com"
      }
    }
  }
}

Cursor

在 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）中，使用 ${env:NAME} 传递每个变量；启动 Cursor 时必须已设置这些变量：

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-api-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "${env:LANGFUSE_PUBLIC_KEY}",
        "LANGFUSE_SECRET_KEY": "${env:LANGFUSE_SECRET_KEY}",
        "LANGFUSE_BASE_URL": "${env:LANGFUSE_BASE_URL}"
      }
    }
  }
}

VS Code（GitHub Copilot）

将密钥声明为 inputs，并设置 "password": true：服务首次启动时，VS Code 会提示输入密钥并安全存储。该文件使用 servers，而非 mcpServers：

{
  "inputs": [
    { "type": "promptString", "id": "langfuse-public-key", "description": "Langfuse public key", "password": true },
    { "type": "promptString", "id": "langfuse-secret-key", "description": "Langfuse secret key", "password": true }
  ],
  "servers": {
    "langfuse": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "langfuse-api-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "${input:langfuse-public-key}",
        "LANGFUSE_SECRET_KEY": "${input:langfuse-secret-key}",
        "LANGFUSE_BASE_URL": "https://cloud.langfuse.com"
      }
    }
  }
}

Codex CLI

Codex 会在启动服务前清理环境。在 ~/.codex/config.toml（或项目的 .codex/config.toml）中的 env_vars 里列出变量名称；Codex 会从自身环境中转发这些变量的值：

[mcp_servers.langfuse]
command = "npx"
args = ["-y", "langfuse-api-mcp"]
env_vars = ["LANGFUSE_PUBLIC_KEY", "LANGFUSE_SECRET_KEY", "LANGFUSE_BASE_URL"]

Gemini CLI — 已验证启动

Gemini CLI 会移除名称中包含 KEY、SECRET 或 TOKEN 的所有变量，因此请在 ~/.gemini/settings.json（或仅在受信任文件夹中读取的项目 .gemini/settings.json）中的 env 里指定这些键：

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-api-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "$LANGFUSE_PUBLIC_KEY",
        "LANGFUSE_SECRET_KEY": "$LANGFUSE_SECRET_KEY",
        "LANGFUSE_BASE_URL": "$LANGFUSE_BASE_URL"
      }
    }
  }
}

Windsurf

在 ~/.config/devin/mcp_config.json（macOS 和 Linux；Windows 上为 %APPDATA%\devin\mcp_config.json）中，使用 ${env:NAME} 转发每个变量：

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-api-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "${env:LANGFUSE_PUBLIC_KEY}",
        "LANGFUSE_SECRET_KEY": "${env:LANGFUSE_SECRET_KEY}",
        "LANGFUSE_BASE_URL": "${env:LANGFUSE_BASE_URL}"
      }
    }
  }
}

配置

设置先读取环境变量，然后读取可选的配置文件中的非敏感设置；环境变量优先。无效值会导致启动失败，并报出一个错误，指出变量名称，但绝不会回显密钥。每条规则、默认值和启动日志行见：配置参考。

连接

变量	必需	含义
`LANGFUSE_PUBLIC_KEY`	是	项目公钥（`pk-lf-…`）。仅限环境变量。
`LANGFUSE_SECRET_KEY`	是	项目密钥（`sk-lf-…`）。仅限环境变量；绝不会记录日志，也绝不会返回给 Agent。
`LANGFUSE_BASE_URL`	是	Langfuse 主机，必须是绝对 `https` URL（仅当主机为回环地址时才允许使用 `http`）。`LANGFUSE_HOST` 可作为别名使用。特意不设默认值。

云区域：EU https://cloud.langfuse.com · US https://us.cloud.langfuse.com · JP https://jp.cloud.langfuse.com · HIPAA https://hipaa.cloud.langfuse.com。密钥仅在创建它们的区域有效。

证书和代理

变量	含义
`LANGFUSE_CA_CERT`	包含一个或多个 CA 证书的 PEM 文件
`LANGFUSE_CA_CERTS_PATH`	PEM 文件目录
`SSL_CERT_FILE`、`SSL_CERT_DIR`、`NODE_EXTRA_CA_CERTS`、`REQUESTS_CA_BUNDLE`、`CURL_CA_BUNDLE`（环境变量）	如果已设置，会自动读取，因此你为其他工具导出的 CA 在此处也能使用
`LANGFUSE_MCP_IGNORE_AMBIENT_CA`	`true` = 不读取环境变量
`HTTPS_PROXY`、`HTTP_PROXY`、`NO_PROXY`（及其小写形式）	标准代理变量；代理协议支持 `http`、`https`、`socks5` 或 `socks5h`，仅支持 Basic 身份验证

受信任的根证书 = 你的操作系统证书存储区 + 上述所有来源中的 CA。最低版本为 TLS 1.2。**没有禁用证书验证的选项。**该服务不会读取 Windows 或 macOS 代理设置，也不会读取 PAC 文件：如何查找代理。

请求限制

变量	默认值	允许的值	含义
`LANGFUSE_MCP_RATE_LIMIT`	Langfuse Cloud 主机为 `30`，其他主机为 `1000`	整数，1 到 60000	服务每分钟发送的 Langfuse 请求数上限，包含重试。使用付费 Cloud 计划时，请将其调高至你的计划限额。
`LANGFUSE_MCP_MAX_CONCURRENCY`	`4`	整数，1 到 64	同时在途的 Langfuse 请求数上限。

结果大小上限

变量	默认值	允许的值	含义
`LANGFUSE_MCP_MAX_RESULT_BYTES`	`65536`（64 KiB）	整数，16384 到 1048576	单个工具结果携带的字节数上限，分别计算其两个副本（作为文本的 JSON 和结构化内容）；超过上限的结果会缩短其中最大的文本值（每个值末尾都会加上 `… [clipped]`），以保留所有行；如果仍然不够，则省略剩余行，并标记为 `truncated`。发现工具的结果（`describe_operation`、`search_operations`）也会控制在此上限内：正文架构会丢失其描述，操作索引则会省略末尾条目。你的 MCP 主机可能有更低的结果显示上限：Claude Code 无法内联显示约 100 KB 的结果，因此只有在主机能显示你设置的值时才调高上限。

行为

变量	默认值	含义
`LANGFUSE_MCP_ALLOW_WRITES`	`false`	将其设为 `true` 可开启写入模式：注册 `execute_write`。只能是 `true` 或 `false`。除非你希望 Agent 修改 Langfuse 数据，否则请保持关闭。
`LANGFUSE_MCP_TRANSPORT`	`stdio`	`http` 会仅在 `127.0.0.1` 上启动 Streamable HTTP，并使用 Bearer 令牌进行保护（计划中）

服务会在启动时检测 Langfuse 版本及其提供的操作，无需进行任何配置（部署配置文件）；升级 Langfuse 后请重启服务。

配置文件（非敏感设置）

要为所有客户端统一设置 CA、主机、代理、限制、结果大小上限或写入模式，请在操作系统的标准配置位置创建配置文件：

操作系统	路径
Linux	`~/.config/langfuse-mcp/config.env`（或 `$XDG_CONFIG_HOME/langfuse-mcp/config.env`）
macOS	`~/Library/Application Support/langfuse-mcp/config.env`
Windows	`%AppData%\langfuse-mcp\config.env`

# KEY=VALUE per line; environment variables win over this file
LANGFUSE_BASE_URL=https://langfuse.internal.example.com
LANGFUSE_CA_CERT=/etc/ssl/private/corp-root.pem
HTTPS_PROXY=http://proxy.example.com:8080

值会按原样读取：不支持引号，也不会展开 ${VAR}。此文件中不允许包含密钥。 如果文件中包含 LANGFUSE_PUBLIC_KEY 或 LANGFUSE_SECRET_KEY，服务将拒绝启动。了解文件的读取方式。

证书场景

你的情况	操作
IT 部门已在操作系统证书存储中安装了企业根 CA（受管 Windows 和 macOS 电脑上很常见）	无需操作。系统证书存储会自动用于验证。
你拿到了 `.pem` / `.crt` 文件	`LANGFUSE_CA_CERT=/path/to/corp-root.pem`
你拿到了证书文件夹	`LANGFUSE_CA_CERTS_PATH=/path/to/certs/`
你的电脑已为其他工具设置 `NODE_EXTRA_CA_CERTS` 或 `REQUESTS_CA_BUNDLE`	无需操作。系统会自动读取这些设置。
你位于 HTTP 代理之后	在环境变量或配置文件中设置 `HTTPS_PROXY`（内部主机还需设置 `NO_PROXY`）；请参阅代理
Docker	以只读方式挂载文件，并将变量指向该文件：`-v /path/to/corp.pem:/certs/corp.pem:ro -e LANGFUSE_CA_CERT=/certs/corp.pem`（请参阅 Docker）。镜像只信任其基础镜像的 CA 包及该文件，不信任其他内容

获取公司根 CA 的 PEM 格式文件：

操作系统	方法
Windows	`certmgr.msc` → 受信任的根证书颁发机构 → 导出为 Base-64 X.509 (.CER)
macOS	钥匙串访问 → 系统根证书 / 系统 → 选择证书 → 文件 → 导出 → `.pem`
Linux	通常位于 `/usr/local/share/ca-certificates/` 或 `/etc/pki/ca-trust/source/anchors/`

启动日志中的 CA sources loaded 行会列出已加载的 CA 来源（路径和数量，不含证书内容）；可用它确认配置是否正确。

安全模型

除非你选择启用，否则只读。 未设置 LANGFUSE_MCP_ALLOW_WRITES=true 时，写入工具不会存在；execute_read 只运行 GET 操作。工具集在启动时固定。
写入模式会对每次破坏性调用进行确认。 启用写入后，创建操作（POST）会直接执行；每次 DELETE、PUT 和 PATCH 操作都必须先在客户端的表单中确认该次具体调用。无法进行表单询问的客户端完全不能运行破坏性操作；没有任何设置可以跳过确认。写入绝不会自动重试。
密钥保留在服务端。 只从服务端的环境中读取，绝不接受来自 Agent 的密钥，绝不记录日志，也绝不在结果中返回。
不可信数据会被标记。 Langfuse 内容会以标明其为数据的信封形式传给 Agent，并清除隐藏的 Unicode 字符和控制字符；即使这些字符是作为转义序列写在追踪输入或输出的 JSON 文本中，也会被清除。
仅使用经过验证的 TLS。 使用操作系统证书库和你的 CA，TLS 1.2+，没有跳过验证的选项。

建议：为 Agent 创建专用的 Langfuse 密钥，为其设置过期日期，并且除非确有需要，否则保持关闭写入。

所有保证及其执行方式、完整的写入确认机制，以及如何验证版本签名，请参阅：安全模型参考。发现漏洞？请私下报告，切勿在公开 issue 中报告：请参阅 SECURITY.md。

不要让 Agent 的环境变量中包含密钥

写入闸门（写入模式关闭，以及写入模式下对每次破坏性调用的确认）仅涵盖通过此服务发出的调用。它无法检测或阻止其他持有相同密钥的进程。如果 MCP 客户端启动时，密钥位于其环境变量中，那么 Agent 运行的每个 shell 命令和工具都会继承这些密钥：例如，当此服务启动失败而 Agent 尝试其他方式时，有 shell 的 Agent 可以使用这些密钥调用 Langfuse 自带的 CLI 或 curl，无需任何确认即可更改你的数据。仅禁止 shell 工具还不够：任何启动会继承该环境变量的进程的工具（脚本运行器、代码解释器、插件）都会造成同样的问题。

将密钥存放在客户端自己的每服务器设置中，而不要放在 shell 中：Claude Code 使用 claude mcp add --env（密钥保存在 ~/.claude.json 中），Claude Desktop 使用 MCPB bundle（保存在操作系统钥匙串中），VS Code 使用 "password": true 的 inputs，或者将字面值写入客户端的 env 块并确保该块不进入代码库。
启动 MCP 客户端的 shell 中，绝不要导出 LANGFUSE_PUBLIC_KEY 或 LANGFUSE_SECRET_KEY。客户端配置下的 ${VAR} 格式代码片段正是为此而设，因此仅在 Agent 无法运行命令时使用。
Agent 仍以你的用户身份运行，因此可以读取存有密钥的文件。如果客户端支持权限规则，请禁止 Agent 读取该文件；若要严格限制，则完全不给 Agent 运行命令的方式。

故障排除

每个故障都会以结构化错误的形式传递给 Agent，其中包含稳定的 code（例如 langfuse_unauthorized、langfuse_rate_limited、tls_untrusted_certificate）、hint 和 retryable 标志。服务绝不会导致连接崩溃，也不会返回机密信息。所有代码请参阅：工具参考。

症状	可能原因	解决方法
服务无法启动；客户端显示启动失败	缺少主机或密钥，或设置无效：服务会以代码 1 退出，并在 stderr 中输出一行 JSON 错误，指出对应变量	查看客户端的 MCP 日志，找到该行，并检查客户端配置中适用于你的客户端的配置片段
Claude Code 在启动时（`/mcp`）将服务显示为 `failed`，且会话未使用该服务运行	服务是在 `v0.1.0` 之前构建的，同时使用 Claude Code 2.1.283，且 Langfuse 对启动探测的响应较慢	使用 `v0.1.0` 或更高版本；Claude Code 2.1.284 会自行恢复（详情）
`x509: certificate signed by unknown authority`，或工具错误 `tls_untrusted_certificate`	企业 CA 不在受信任证书池中	设置 `LANGFUSE_CA_CERT`（PEM 文件）或 `LANGFUSE_CA_CERTS_PATH`（目录），然后检查启动日志中是否有 "CA sources loaded"
工具错误 `network_error`	主机错误、DNS 或代理问题	检查 `LANGFUSE_BASE_URL` 中的主机；如果使用代理，请检查 `HTTPS_PROXY`/`NO_PROXY`；启动日志中的 `proxy` 行会显示正在使用的代理
工具错误 `langfuse_unauthorized`（HTTP 401）	密钥对错误，或密钥来自其他区域	检查 `LANGFUSE_PUBLIC_KEY` 和 `LANGFUSE_SECRET_KEY`，并确认 `LANGFUSE_BASE_URL` 是密钥所属区域的主机：密钥只能在其所属区域使用
工具错误 `langfuse_rate_limited`（HTTP 429）	已达到 Langfuse 的速率限制	如果 Langfuse 指定的 `Retry-After` 等待时间符合 60 s 请求时限，则读取操作已经重试过一次。再次调用前，请等待 `retryAfterSeconds`（`0` 表示 Langfuse 未指定等待时间，请退避）。部分套餐的指标操作有较低的每日预算。对于 Langfuse Cloud 主机，服务自身的限制（请求限制）默认为每分钟 30 个请求
工具错误 `timeout`，且 `retryable: true`	调用等待服务自身的请求限制，超过了时限；请求尚未发送到 Langfuse	减少同时发起的调用次数；如果你的 Langfuse 套餐允许，也可以提高 `LANGFUSE_MCP_RATE_LIMIT`/`LANGFUSE_MCP_MAX_CONCURRENCY`
工具错误 `timeout`，且 `retryable: false`	Langfuse 在 60 s 请求时限内未作出响应	根据操作支持的参数缩小查询范围：减少 `fields` 中的字段组，降低 `limit`，或缩短时间范围（提示只会列出该操作支持的参数）。如果操作不支持这些参数，例如 Langfuse 3.80.0 上的 `trace_get` 或 `legacy_observationsV1_get`，则无法通过此服务降低其开销；提示会建议告知用户
Agent 表示无法更改数据；其工具列表中没有 `execute_write`	写入模式已关闭（默认设置）：未注册 `execute_write`，且发现工具会隐藏写入操作	设置 `LANGFUSE_MCP_ALLOW_WRITES=true`（环境变量或配置文件），然后重启服务：工具集在启动时固定
删除或更新失败，错误为 `confirmation_unavailable`	客户端无法显示表单（不支持 MCP 表单征询），因此服务无法请求你确认此破坏性调用；未发送任何内容	使用支持表单征询的客户端。没有任何设置可以跳过确认
删除或更新失败，错误为 `confirmation_declined`，但你没有看到表单	客户端自行响应了服务的表单。在 2026-10-11 的 Claude 桌面应用（2.1.295）Code 选项卡中观察到此情况；Claude Code 终端 CLI（2.1.296）则显示了表单。未发送任何内容	使用会显示表单的客户端发起调用，例如 Claude Code 终端 CLI；或者在 Langfuse UI 中进行更改

了解更多

文档索引：工具、配置、安装与安全的参考资料，以及服务的构建方式。
贡献指南：构建、测试，以及拉取请求必须通过的检查。

参考资料

Langfuse 文档：https://langfuse.com/docs
API 参考：https://api.reference.langfuse.com
数据区域：https://langfuse.com/security/data-regions
MCP 规范：https://modelcontextprotocol.io
Go SDK：https://github.com/modelcontextprotocol/go-sdk
OWASP GenAI Security Project：https://genai.owasp.org
OWASP MCP Top 10：https://github.com/OWASP/www-project-mcp-top-10
Node.js 企业网络配置（解释基于 Node 的工具为何会在企业 CA 环境下失效）：https://nodejs.org/learn/http/enterprise-network-configuration

许可证

Apache-2.0。可免费用于商业用途，并明确授予专利许可。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

Langfuse API

关于 Langfuse API

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

langfuse-api-mcp

简介

适用场景

与官方 Langfuse MCP 的区别

工具

用户技能

安装和运行

npx

发布归档

Docker

Claude Desktop（MCPB）

go install

客户端配置

Claude Code — 已验证

Claude Desktop

Cursor

VS Code（GitHub Copilot）

Codex CLI

Gemini CLI — 已验证启动

Windsurf

配置

连接

证书和代理

请求限制

结果大小上限

行为

配置文件（非敏感设置）

证书场景

安全模型

不要让 Agent 的环境变量中包含密钥

故障排除

了解更多

参考资料

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？