Langfuse MCP Java

What log-logn/langfuse-mcp-java MCP server does

The log-logn/langfuse-mcp-java MCP server connects an MCP-compatible agent to a Langfuse project. Its tools cover trace and observation inspection, exception investigation, session browsing, prompt lifecycle management, evaluation datasets, dataset runs, scores, cost metrics, and other Langfuse project resources described by the API.

Trace tools support paginated filtering by user, trace name, session, tags, and time range. An agent can retrieve complete trace details, including nested observations, inputs and outputs, metadata, latency, and token usage. Error-focused tools find traces at the ERROR level, locate errors using file-name metadata, retrieve exception details, and count errors within a time range.

The server also exposes write operations. Agents can create prompt versions, change prompt labels, create datasets and items, link run items to traces or observations, and delete traces, prompts, dataset items, or dataset runs. Deletion operations are irreversible.

How it works

The application is built with Java 21, Spring Boot, and Spring AI. It serves the MCP endpoint at /mcp over Streamable HTTP on port 8080. Health information is available at /actuator/health, and /ping provides a simple ping endpoint.

The log-logn/langfuse-mcp-java MCP server forwards authenticated requests to the configured Langfuse host. List operations use one-based pagination; the documented default page is 1 and the default limit is 20, with limits capped at 100 where specified. Responses use an ApiResponse envelope, while paginated results include item data and page metadata.

Setup and configuration

Build the project with Maven 3.9 or later using mvn clean package -DskipTests, then start the generated Spring Boot JAR with Java. Docker can build the application without a local Maven installation and expose port 8080.

Set these required environment variables before starting the server:

• LANGFUSE_PUBLIC_KEY: the Langfuse project public key.
• LANGFUSE_SECRET_KEY: the Langfuse project secret key.
• LANGFUSE_HOST: the Langfuse base URL, such as the Langfuse Cloud URL or a self-hosted instance.

LANGFUSE_TIMEOUT is optional and accepts Spring Duration values such as 30s or 1m; its documented default is 30 seconds. The host may include a trailing slash because the application normalizes it.

Configure clients with http://localhost:8080/mcp. The README provides configurations for Cursor and Claude Desktop, as well as URL and command modes for VS Code or GitHub Copilot.

Tools and capabilities

The log-logn/langfuse-mcp-java MCP server includes tools for:

• Browsing traces, observations, sessions, users, and exceptions.
• Reading, creating, deleting, and labeling prompt versions.
• Managing datasets, dataset items, experiment runs, and run items.
• Querying scores, score configurations, cost metrics, token usage, latency, and related analytics.
• Inspecting project, schema, model, connection, annotation, comment, and evaluation resources where supported by the exposed tools.

Prompt tools support both plain text prompts and chat prompts represented as JSON message arrays. Dataset creation accepts optional descriptions, metadata, input schemas, and expected-output schemas as JSON strings.

Limitations and notes

The server requires a Langfuse account or self-hosted Langfuse instance with an API key pair. It is an HTTP-transport server; the documented MCP endpoint is /mcp, and the legacy /sse endpoint is not used. Some operations require identifiers such as traceId, sessionId, datasetName, runName, or userId. Error counting scans up to 500 traces. Deletion tools permanently remove data and should not be invoked without confirmation.