使用说明

廊坊MCP服务器——Java/Spring AI

一个生产级MCP服务器，将任何兼容MCP的AI代理连接到您的Langfuse可观察性数据。
查询跟踪、调试错误、检查会话、管理提示、运行评估、注释数据和配置模型——所有这些都是通过自然语言完成的。

运输： 端口8080上的流式HTTP，与Cursor、Claude Desktop、VS Code/GitHub Copilot以及任何支持HTTP传输的MCP客户端兼容。

为什么是这个服务器？

能力	此服务器	Langfuse MCP官方
痕迹和观察	✅	❌
会话和用户	✅	❌
异常跟踪	✅	❌
提示管理（读+写）	✅	✅ 只读
数据集和运行管理	✅	❌
分数和分数配置	✅	❌
注释队列	✅	❌
评论	✅	❌
模型定义	✅	❌
LLM连接	✅	❌
项目反思	✅	❌
模式自省	✅	❌
Java/Spring人工智能✅	❌ python

先决条件

Java 21 或更高版本
Maven 3.9+ （或使用Docker构建——不需要本地Maven）
A. 廊坊具有API密钥对的帐户(public-key + secret-key)

快速开始

# 1. Build
mvn clean package -DskipTests

# 2. Set credentials
export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...
export LANGFUSE_HOST=https://cloud.langfuse.com

# 3. Run (Streamable HTTP transport — port 8080)
java -jar target/langfuse-mcp-1.0.0.jar

# 4. Verify
curl http://localhost:8080/actuator/health

# 5. Inspect all tools
npx @modelcontextprotocol/inspector http://localhost:8080/mcp

从获取凭据朗富士云 → 设置→ API密钥。
自助式廊坊？集 LANGFUSE_HOST 到您的实例URL。

配置

所有配置均由环境变量驱动（或 application.yml 用于本地覆盖）。

属性	环境变量	必需	默认值	描述
`langfuse.public-key`	`LANGFUSE_PUBLIC_KEY`	✅	—	廊坊项目公钥
`langfuse.secret-key`	`LANGFUSE_SECRET_KEY`	✅	—	Langfuse项目密钥
`langfuse.host`	`LANGFUSE_HOST`	✅	—	Langfuse基本URL，例如。 `https://cloud.langfuse.com`
`langfuse.timeout`	`LANGFUSE_TIMEOUT`	❌	`30s`	HTTP请求超时——Spring持续时间格式，例如。 `30s`, `1m`, `90s`
`langfuse.read-only`	—	❌	`true`	信息标志；写操作可以通过特定的工具进行

尾随斜线处理

LANGFUSE_HOST 可以指定带有或不带有尾随斜线——服务器会自动对其进行标准化。

客户端配置

光标(`.cursor/mcp.json`)

{
  "mcpServers": {
    "langfuse": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

克劳德桌面(`claude_desktop_config.json`)

{
  "mcpServers": {
    "langfuse": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

在macOS上： ~/Library/Application Support/Claude/claude_desktop_config.json

VS代码/GitHub副本

URL模式：

{
  "github.copilot.chat.mcp.servers": {
    "langfuse": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

命令模式 （仅限stdio客户端）：

{
  "github.copilot.chat.mcp.servers": {
    "langfuse": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/langfuse-mcp-1.0.0.jar"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-...",
        "LANGFUSE_SECRET_KEY": "sk-lf-...",
        "LANGFUSE_HOST": "https://cloud.langfuse.com"
      }
    }
  }
}

注： MCP端点为 /mcp （可流式传输HTTP）。传统的苏格兰和南方能源公司 /sse 此服务器未使用终结点。

码头工人

这 Dockerfile 是一个多阶段构建：它在Docker中编译Spring Boot jar，并在端口上运行MCP服务器 8080不需要本地安装Maven。

# Build image (compiles inside Docker)
docker build -t langfuse-mcp:latest .

# Run
docker run --rm -p 8080:8080 \
  -e LANGFUSE_PUBLIC_KEY=pk-lf-... \
  -e LANGFUSE_SECRET_KEY=sk-lf-... \
  -e LANGFUSE_HOST=https://cloud.langfuse.com \
  langfuse-mcp:latest

容器启动后：

端点	URL
健康检查	`http://localhost:8080/actuator/health`
Ping	`http://localhost:8080/ping`
MCP端点	`http://localhost:8080/mcp`

Langfuse在同一主机上的另一个容器中运行：

-e LANGFUSE_HOST=http://host.docker.internal:3000

工具参考（共55个）

每个工具都返回一致的 ApiResponse<T> 信封：

{ "success": true,  "data": { ... }, "timestamp": "2025-01-15T10:30:00Z" }
{ "success": false, "errorCode": "TRACE_NOT_FOUND", "errorMessage": "...", "timestamp": "..." }

分页列表响应将其项目包装在一个 PagedResponse<T>:

{
  "data": [ ... ],
  "meta": { "page": 1, "limit": 20, "totalItems": 142, "totalPages": 8 }
}

分页是基于1的(page 默认为 1). limit 默认为 20 并且上限为 100 如有注明。要浏览结果，请递增 page 同时保持 limit 固定的。

痕迹（8个工具）

工具	说明
`fetch_traces`	分页的痕迹列表。筛选依据 `userId`, `name`, `sessionId`, `tags`, `fromTimestamp`, `toTimestamp`.
`fetch_trace`	单个跟踪的完整细节，包括嵌套观察、输入/输出、元数据、延迟和令牌使用。需要 `traceId`.
`find_exceptions`	痕迹谁 `level` 等于 `ERROR`.支持时间范围和分页。
`find_exceptions_in_file`	元数据包含给定文件名子字符串的错误级别跟踪。需要 `fileName`.
`get_exception_details`	单个错误跟踪的完整细节。需要 `traceId`.
`get_error_count`	计数 `ERROR`-时间范围内的电平跟踪（扫描多达500条跟踪）。
`delete_trace`	按ID永久删除单个跟踪。不可逆转。
`delete_traces`	永久删除多个痕迹。传递一个以逗号分隔的跟踪ID列表。不可逆转。

会话（3个工具）

工具	说明
`fetch_sessions`	带有可选时间范围过滤器的分页会话列表。
`get_session_details`	完整的会话细节，包括其所有痕迹。需要 `sessionId`.
`get_user_sessions`	具有分页的特定用户的所有会话。需要 `userId`.

提示（5个工具）

工具	说明
`list_prompts`	项目中所有提示的分页列表。
`get_prompt`	按名称获取提示。可选地固定到 `version` 数字或a `label` （例如。 `production`, `staging`).
`create_prompt`	创建新提示或将新版本附加到现有提示。 `type` 是 `text` （纯字符串）或 `chat` （JSON数组 `{role, content}` 消息）。支持逗号分隔 `labels` 和 `tags`.
`delete_prompt`	按名称删除提示版本。特定范围 `label` 或 `version`；省略两者以删除所有版本。不可逆转。
`update_prompt_labels`	替换特定提示版本上的完整标签集。提供一个空字符串以删除所有标签。这 `latest` 标签由Langfuse保留。

数据集（7个工具）

工具	说明
`list_datasets`	所有评估数据集的分页列表。
`get_dataset`	按确切名称获取数据集。
`create_dataset`	创建新数据集。可选供应 `description`, `metadataJson`, `inputSchemaJson`，以及 `expectedOutputSchemaJson` （全部为JSON字符串）。
`list_dataset_items`	数据集中的分页项目列表。需要 `datasetName`.
`get_dataset_item`	按ID获取单个数据集项
`create_dataset_item`	创建或追加销售数据集项。可选链接到 `sourceTraceId` 或 `sourceObservationId`.支持 `itemId` 用于扰乱语义。
`delete_dataset_item`	按ID永久删除数据集项。不可逆转。

数据集运行（5个工具）

工具	说明
`list_dataset_runs`	数据集的实验运行分页列表。需要 `datasetName`.
`get_dataset_run`	完整的跑步细节，包括所有跑步项目。需要 `datasetName` 和 `runName`.
`delete_dataset_run`	删除跑步记录及其所有项目。不可逆转。需要 `datasetName` 和 `runName`.
`list_dataset_run_items`	跑步中项目的分页列表。需要 `datasetId` 和 `runName`.
`create_dataset_run_item`	创建一个运行项，将数据集项链接到跟踪/观察。如果运行尚不存在，则自动创建运行。

指标（1个工具）

工具	说明
`get_cost_metrics`	通过Metrics API v1查询Langfuse成本、令牌、延迟和使用分析。镜像：GET/api/public/metrics？查询=。将完整查询作为JSON字符串传递。所有聚合都是服务器端的。

此工具接受单个必需参数 query 其必须是与度量API模式匹配的JSON串行化字符串。示例（将这些作为单个JSON字符串传递）：

过去7天的总成本：

{“视图”：“跟踪”，“指标”：[{“度量”：“总成本”，“聚合”：“总和”}]，“来自时间戳”：“2026-03-18T00:00:00Z”，“到时间戳”:“2026-03-25T23:59:59Z”}
本周每日成本趋势：

{“视图”：“跟踪”，“指标”：[{“度量”：“总成本”，“聚合”：“总和”}，{“度量值”：“计数”，“聚集”：“计数值”}]，“时间维度”：{“粒度”：“天”}，“从时间戳”：“2026-03-18T00:00:00Z”，“到时间戳”:“2026-03-25T23:59:59Z”}
按型号列出的成本：

{“view”：“observation”，“dimensions”：[{“field”：“providedModelName”}]，“metrics”：[｛“measures”：“totalCost”，“aggregation”：“sum”}，{“measure”：“totalTokens”，“聚合”：“summ”}]
特定用户的成本：

{“view”：“traces”，“metrics”：[{“measure”：“totalCost”，“aggregation”：“sum”]，“filters”：[｛“column”：“userId”，“operator”：“=”，“value”：“user-123”，“type”：“string”}，“fromTimestamp”：“2026-03-18T00:00:00Z”，“toTimestamp”:“2026-03-25T23:59:59Z”}
仅生产环境：

筛选器：〔｛“列”：“环境”，“运算符”：“=”，“值”：“生产”，“类型”：“字符串”｝〕

分数（6个工具）

工具	说明
`get_scores`	分页的评估分数列表。筛选依据 `traceId`, `observationId`, `name`, `dataType` (`NUMERIC`
`get_score`	按ID获取单个分数
`get_score_configs`	分数配置模式分页列表。
`get_score_config`	按ID获取单个分数配置
`create_score_config`	创建分数配置。 `NUMERIC` 支持可选 `minValue`/`maxValue`. `CATEGORICAL` 接受a `categoriesJson` 数组 `{label, value}` 物体。
`update_score_config`	更新现有的分数配置。可选设置 `isArchived` 将其存档

注释队列（8个工具）

工具	说明
`list_annotation_queues`	注释队列的分页列表。
`get_annotation_queue`	按ID获取单个队列
`create_annotation_queue`	创建一个用于人工循环审查的队列。可选链接a `scoreConfigId`.
`list_annotation_queue_items`	队列中项目的分页列表。可选过滤条件 `status` (`PENDING`
`get_annotation_queue_item`	通过以下方式获取特定队列项 `queueId` 和 `itemId`.
`create_annotation_queue_item`	将跟踪、观察或会话添加到队列中以供查看。 `objectType` 是 `TRACE`, `OBSERVATION`，或 `SESSION`.
`update_annotation_queue_item`	更新队列项目的状态(`PENDING`
`delete_annotation_queue_item`	从队列中删除项目。不可逆转。

评论（3个工具）

工具	说明
`get_comments`	分页的评论列表。可选过滤条件 `objectType` (`TRACE`
`get_comment`	按ID获取单个评论
`create_comment`	为跟踪、观察、会话或提示添加注释。 `objectType` 值： `TRACE`, `OBSERVATION`, `SESSION`, `PROMPT`.

模型（4个工具）

工具	说明
`list_models`	所有模型定义（Langfuse管理和自定义）的分页列表。
`get_model`	按ID获取模型定义
`create_model`	创建用于成本跟踪的自定义模型。需要 `modelName`, `matchPattern` （正则表达式），以及 `unit` (`TOKENS`
`delete_model`	删除自定义模型定义。无法删除Langfuse管理的模型。不可逆转。

LLM连接（2个工具）

工具	说明
`list_llm_connections`	LLM提供程序连接的分页列表（密钥在响应中被屏蔽）。
`upsert_llm_connection`	通过以下方式创建或更新提供程序连接 `provider` 名称（例如。 `openai`, `anthropic`, `azure`, `google`).按提供程序更新——如果连接已存在，则进行更新。

项目（1个工具）

工具	说明
`get_projects_for_api_key`	返回对已配置的API键可见的项目。可用于确认凭据和项目元数据。

用户（1个工具）

工具	说明
`get_user_traces`	带有分页的特定Langfuse用户ID的所有跟踪。需要 `userId`.

模式（1个工具）

工具	说明
`get_data_schema`	返回完整的Langfuse数据模型：所有实体类型、字段和有效枚举值。在运行查询之前，请先调用此命令以了解可用的数据结构。

建筑

MCP Client (Cursor / Claude Desktop / Copilot / other)
    │   Streamable HTTP transport (/mcp)
    ▼
Tool class  (@McpTool — validates required params, delegates to service)
    ▼
Service interface + impl  (business logic, filtering, error mapping)
    ▼
LangfuseApiClient  (HTTP gateway — GET / POST / PATCH / DELETE, typed exceptions)
    ▼
Langfuse Public REST API

该架构严格分层：

client/ --Langfuse集成边界：HTTP与Basic Auth（Apache HttpComponents 5）、类型异常、， UriComponentsBuilder 查询参数
service/ --域逻辑：过滤、映射、分页、错误转换为 ApiResponse
tools/ --MCP表面：对代理友好的描述、参数验证、服务委托
Spring Boot --仅限运行时和传输包装器

API客户端

LangfuseApiClient 支持四种HTTP方法。所有方法throw LangfuseApiException 或 ResourceNotFoundException 关于错误，服务层将其转换为结构化 ApiResponse.error(...) 响应——代理永远看不到原始堆栈跟踪。

方法	用于
`GET`	所有读取操作
`POST`	创建操作
`PATCH`	更新操作
`DELETE`	删除操作

包结构

com.langfuse.mcp
├── LangfuseMcpApplication.java          @SpringBootApplication @ConfigurationPropertiesScan
├── config/
│   ├── LangfuseProperties.java          @ConfigurationProperties — publicKey, secretKey, host, timeout, readOnly
│   ├── LangfuseClientConfig.java        RestClient bean — Basic-Auth, Apache HttpComponents 5, configurable timeout
│   └── JacksonConfig.java               Primary ObjectMapper (JSR310, ignore unknown fields)
├── client/
│   └── LangfuseApiClient.java           HTTP gateway (GET/POST/PATCH/DELETE); typed exceptions; UriComponentsBuilder queries
├── controller/
│   └── PingController.java              GET /ping → {"status":"ok"}
├── exception/
│   ├── LangfuseApiException.java        Wraps HTTP/connectivity errors — statusCode + endpoint
│   └── ResourceNotFoundException.java   Thrown on HTTP 404
├── dto/
│   ├── common/    ApiResponse · PagedResponse · PaginationMeta
│   ├── request/   Filter/get request classes (12 classes)
│   └── response/  Response classes (19 classes — JsonNode for open-schema fields)
├── service/       Interfaces (15): Trace · Session · Prompt · PromptWrite · Dataset · DatasetRun
│   │              · Score · AnnotationQueue · Comment · Model · LlmConnection · Project · User · Schema · CostMetrics
│   └── impl/      *ServiceImpl (15) — business logic, filtering, error mapping
├── tools/         @McpTool classes (15) — param validation, delegation, agent-friendly descriptions
│   ├── TraceTools.java             (8 tools)
│   ├── SessionTools.java           (3 tools)
│   ├── PromptTools.java            (2 tools)
│   ├── PromptWriteTools.java       (3 tools)
│   ├── DatasetTools.java           (7 tools)
│   ├── DatasetRunTools.java        (5 tools)
│   ├── ScoreTools.java             (6 tools)
│   ├── AnnotationQueueTools.java   (8 tools)
│   ├── CommentTools.java           (3 tools)
│   ├── ModelTools.java             (4 tools)
│   ├── LlmConnectionTools.java     (2 tools)
│   ├── ProjectTools.java           (1 tool)
│   ├── UserTools.java              (1 tool)
│   ├── SchemaTools.java            (1 tool)
│   └── CostMetricsTools.java       (1 tool)
└── util/
    └── JsonPageMapper.java         Centralised JSON → PagedResponse mapper (no duplication)

运行测试

mvn test

测试覆盖范围包括：

LangfusePropertiesBindingTest --配置绑定来自 application-test.yml 以及属性级别验证
PromptWriteServiceImplTest --用于快速创建/删除/标签更新的服务逻辑
ProjectServiceImplTest -API项目响应映射
ObservationServiceImplTest --观测数据提取和野外测绘
MetricsServiceImplTest --度量聚合逻辑

测试使用 spring.ai.mcp.server.enabled=false （设置在 src/test/resources/application-test.yml)因此在测试执行期间不启动MCP传输。

故障排除

`TRACE_FETCH_ERROR: HTTP/1.1 header parser received no bytes`

连接问题——不是代码错误。检查：

LANGFUSE_HOST 指向一个正在运行的Langfuse实例
可以从JVM进程访问主机
对于Docker：使用 host.docker.internal 而不是 localhost
该方案与您的服务器匹配(http:// 对比 https://)
确认API已启动： curl $LANGFUSE_HOST/api/public/health

`INVALID_INPUT: <param> is required`

未提供必需的参数。全部 required = true 在进行任何HTTP调用之前，在工具层验证参数。

连接超时

增加超时时间：

export LANGFUSE_TIMEOUT=60s

代理无法看到服务器

确认服务器正在运行： curl http://localhost:8080/actuator/health
确认MCP端点可达： curl http://localhost:8080/ping
检查客户端配置URL是否指向 http://localhost:8080/mcp
检查所有可用工具： npx @modelcontextprotocol/inspector http://localhost:8080/mcp

Langfuse管理的模型无法删除

delete_model 仅适用于您创建的自定义模型定义。要覆盖Langfuse管理模型的定价，请创建一个具有相同定价的新自定义模型 modelName.

Langfuse MCP服务器

使用说明

廊坊MCP服务器——Java/Spring AI

为什么是这个服务器？

先决条件

快速开始

配置

尾随斜线处理

客户端配置

光标(`.cursor/mcp.json`)

克劳德桌面(`claude_desktop_config.json`)

VS代码/GitHub副本

码头工人

工具参考（共55个）

痕迹（8个工具）

会话（3个工具）

提示（5个工具）

数据集（7个工具）

数据集运行（5个工具）

指标（1个工具）

分数（6个工具）

注释队列（8个工具）

评论（3个工具）

模型（4个工具）

LLM连接（2个工具）

项目（1个工具）

用户（1个工具）

模式（1个工具）

建筑

API客户端

包结构

运行测试

故障排除

`TRACE_FETCH_ERROR: HTTP/1.1 header parser received no bytes`

`INVALID_INPUT: <param> is required`

连接超时

代理无法看到服务器

Langfuse管理的模型无法删除

许可证

使用说明

廊坊MCP服务器——Java/Spring AI

为什么是这个服务器？

先决条件

快速开始

配置

尾随斜线处理

客户端配置

光标(.cursor/mcp.json)

克劳德桌面(claude_desktop_config.json)

VS代码/GitHub副本

码头工人

工具参考（共55个）

痕迹（8个工具）

会话（3个工具）

提示（5个工具）

数据集（7个工具）

数据集运行（5个工具）

指标（1个工具）

分数（6个工具）

注释队列（8个工具）

评论（3个工具）

模型（4个工具）

LLM连接（2个工具）

项目（1个工具）

用户（1个工具）

模式（1个工具）

建筑

API客户端

包结构

运行测试

故障排除

TRACE_FETCH_ERROR: HTTP/1.1 header parser received no bytes

INVALID_INPUT: <param> is required

连接超时

代理无法看到服务器

Langfuse管理的模型无法删除

许可证

相关 MCP

MCP服务发现与推荐工具

贡献查询工具

SEO数据分析MCP服务器

区块链监控服务器

文献搜索服务

地震数据MCP服务器

光标(`.cursor/mcp.json`)

克劳德桌面(`claude_desktop_config.json`)

`TRACE_FETCH_ERROR: HTTP/1.1 header parser received no bytes`

`INVALID_INPUT: <param> is required`