README.md
A production-hardened, read-only MCP server for Langfuse observability data.
Langfuse MCP Server — Java / Spring AI
A production-hardened, read-only MCP server that connects any MCP-compatible AI agent to your Langfuse observability data.
Query traces, debug errors, inspect sessions, analyze prompts, and explore datasets — all through natural language.
Transport: HTTP/SSE on port 8080, compatible with Cursor and Claude Desktop out of the box.
Why this server?
| Capability | This server | Official Langfuse MCP |
|---|---|---|
| Traces & Observations | ✅ | ❌ |
| Sessions & Users | ✅ | ❌ |
| Exception tracking | ✅ | ❌ |
| Prompt management | ✅ | ✅ |
| Dataset management | ✅ | ❌ |
| Scores & metrics | ✅ | ❌ |
| Schema introspection | ✅ | ❌ |
| Java / Spring AI | ✅ | ❌ (Python) |
| Read-only by design | ✅ | N/A |
Tools (24 total)
| Category | Count | Tools |
|---|---|---|
| Traces | 6 | fetch_traces, fetch_trace, find_exceptions, find_exceptions_in_file, get_exception_details, get_error_count |
| Observations | 2 | fetch_observations, fetch_observation |
| Sessions | 3 | fetch_sessions, get_session_details, get_user_sessions |
| Prompts | 2 | list_prompts, get_prompt |
| Datasets | 4 | list_datasets, get_dataset, list_dataset_items, get_dataset_item |
| Scores | 4 | get_scores, get_score, get_score_configs, get_score_config |
| Users | 1 | get_user_traces |
| Comments | 1 | get_comments |
| Schema | 1 | get_data_schema |
Quick start
# 1. Build
mvn clean package
# 2. Set credentials
export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...
export LANGFUSE_HOST=https://cloud.langfuse.com
# 3. Run (SSE 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/sse
Get credentials from Langfuse Cloud → Settings → API Keys.
Self-hosted Langfuse? Set LANGFUSE_HOST to your instance URL.
Architecture
MCP Client (Cursor / Claude Desktop / other)
│ HTTP/SSE transport (/sse + /mcp/message)
▼
Tool class (@McpTool — thin delegation layer, validates required params)
▼
Service interface + impl (business logic, error mapping, server-side filtering)
▼
LangfuseApiClient (GET-only HTTP gateway, typed exceptions)
▼
Langfuse Public REST API
The architecture is strictly layered:
client/— Langfuse integration boundary (HTTP, Basic-Auth, error handling)service/— domain logic (filtering, mapping, pagination)tools/— MCP-facing surface (descriptions, param validation, delegation)- Spring Boot — runtime and transport wrapper only
Read-only by design: LangfuseApiClient exposes only GET methods. No POST, PATCH, or DELETE operations exist anywhere in the codebase. The langfuse.read-only=true flag is enforced at the properties level.
Every tool returns a consistent ApiResponse<T> envelope:
{ "success": true, "data": { ... }, "timestamp": "2025-01-15T10:30:00Z" }
{ "success": false, "errorCode": "TRACE_NOT_FOUND", "errorMessage": "...", "timestamp": "..." }
Configuration
| Property | Env var | Required | Default | Description |
|---|---|---|---|---|
langfuse.public-key |
LANGFUSE_PUBLIC_KEY |
✅ | — | Langfuse project public key |
langfuse.secret-key |
LANGFUSE_SECRET_KEY |
✅ | — | Langfuse project secret key |
langfuse.host |
LANGFUSE_HOST |
✅ | — | Langfuse base URL |
langfuse.timeout |
LANGFUSE_TIMEOUT |
❌ | 30s |
HTTP request timeout (Spring Duration format, e.g. 30s, 1m) |
langfuse.read-only |
— | ❌ | true |
Safety flag — always true, no writes are possible |
Client config
Cursor (`.cursor/mcp.json`)
{
"mcpServers": {
"langfuse": {
"url": "http://localhost:8080/sse"
}
}
}
Claude Desktop (`claude_desktop_config.json`)
{
"mcpServers": {
"langfuse": {
"url": "http://localhost:8080/sse"
}
}
}
On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
VS Code / GitHub Copilot
URL mode (if your client supports it):
{
"github.copilot.chat.mcp.servers": {
"langfuse": {
"url": "http://localhost:8080/sse"
}
}
}
Command mode (stdio-only clients):
{
"github.copilot.chat.mcp.servers": {
"langfuse": {
"command": "java",
"args": ["-jar", "/path/to/langfuse-mcp-1.0.0.jar"],
"env": {
"LANGFUSE_PUBLIC_KEY": "pk-lf-...",
Tools (8)
fetch_tracesRetrieve a list of traces from Langfuse.fetch_traceGet details for a specific trace.find_exceptionsSearch for exceptions within traces.get_error_countGet the count of errors recorded.fetch_sessionsList user sessions.list_promptsList available prompts in Langfuse.list_datasetsList available datasets.get_data_schemaRetrieve the data schema for introspection.Environment Variables
LANGFUSE_PUBLIC_KEYrequiredLangfuse project public keyLANGFUSE_SECRET_KEYrequiredLangfuse project secret keyLANGFUSE_HOSTrequiredLangfuse base URLLANGFUSE_TIMEOUTHTTP request timeoutConfiguration
claude_desktop_config.json
{"mcpServers": {"langfuse": {"url": "http://localhost:8080/sse"}}}Try it
→Find the most recent traces that resulted in an exception.
→List all available datasets and their items.
→Get the details for the session associated with user ID 'user-123'.
→Retrieve the latest prompt version from Langfuse.
→Show me the error count for the last 24 hours.