log-logn/langfuse-mcp-java

A production-grade MCP server that connects any MCP-compatible AI agent to your Langfuse observability data.
Query traces, debug errors, inspect sessions, manage prompts, run evaluations, annotate data, and configure models — all through natural language.
> **Transport:** Streamable HTTP on port 8080, compatible with Cursor, Claude Desktop, VS Code / GitHub Copilot, and any MCP client that supports HTTP transport.
---
Why this server?
| Capability | This server | Official Langfuse MCP |
|---|---|---|
| Traces & Observations | ✅ | ❌ |
| Sessions & Users | ✅ | ❌ |
| Exception tracking | ✅ | ❌ |
| Prompt management (read + write) | ✅ | ✅ read-only |
| Dataset & run management | ✅ | ❌ |
| Scores & score configs | ✅ | ❌ |
| Annotation queues | ✅ | ❌ |
| Comments | ✅ | ❌ |
| Model definitions | ✅ | ❌ |
| LLM connections | ✅ | ❌ |
| Project introspection | ✅ | ❌ |
| Schema introspection | ✅ | ❌ |
| Java / Spring AI | ✅ | ❌ (Python) |
---
Prerequisites
- **Java 21** or later
- **Maven 3.9+** (or use the Docker build — no local Maven required)
- A Langfuse account with an API key pair (public-key + secret-key)
---
Quick Start
Get credentials from Langfuse Cloud → Settings → API Keys.
Self-hosted Langfuse? Set LANGFUSE_HOST to your instance URL.
---
Configuration
All configuration is driven by environment variables (or application.yml for local overrides).
| 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, e.g. https://cloud.langfuse.com |
| langfuse.timeout | LANGFUSE_TIMEOUT | ❌ | 30s | HTTP request timeout — Spring Duration format, e.g. 30s, 1m, 90s |
| langfuse.read-only | — | ❌ | true | Informational flag; write operations are available through specific tools |
Trailing slash handling
LANGFUSE_HOST may be specified with or without a trailing slash — the server normalises it automatically.
---
Client Configuration
Cursor (.cursor/mcp.json)
Claude Desktop (claude_desktop_config.json)
On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
VS Code / GitHub Copilot
**URL mode:**
**Command mode** (stdio-only clients):
> **Note:** The MCP endpoint is /mcp (streamable HTTP). The legacy SSE /sse endpoint is not used by this server.
---
Docker
The Dockerfile is a multi-stage build: it compiles the Spring Boot jar inside Docker and runs the MCP server on port 8080. No local Maven installation is needed.
After the container starts:
| Endpoint | URL |
|---|---|
| Health check | http://localhost:8080/actuator/health |
| Ping | http://localhost:8080/ping |
| MCP endpoint | http://localhost:8080/mcp |
**Langfuse running in another container on the same host:**
---
Tools Reference (55 total)
Every tool returns a consistent ApiResponse envelope:
Paginated list responses wrap their items in a PagedResponse :
Pagination is 1-based (page defaults to 1). limit defaults to 20 and is capped at 100 where noted. To page through results, increment page while keeping limit fixed.
---
Traces (8 tools)
| Tool | Description |
|---|---|
| fetch_traces | Paginated list of traces. Filter by userId, name, sessionId, tags, fromTimestamp, toTimestamp. |
| fetch_trace | Full detail of a single trace including nested observations, input/output, metadata, latency, and token usage. Requires traceId. |
| find_exceptions | Traces whose level equals ERROR. Supports time range and pagination. |
| find_exceptions_in_file | Error-level traces whose metadata contains a given file name substring. Requires fileName. |
| get_exception_details | Full detail of a single error trace. Requires traceId. |
| get_error_count | Count of ERROR-level traces in a time range (scans up to 500 traces). |
| delete_trace | Permanently deletes a single trace by ID. **Irreversible.** |
| delete_traces | Permanently deletes multiple traces. Pass a comma-separated list of trace IDs. **Irreversible.** |