langfuse-mcp-java

Langfuse MCP Server — Java / Spring AI

!Spring Boot !Spring AI !Java !Lombok

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

# 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

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)

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

Claude Desktop (claude_desktop_config.json)

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

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

VS Code / GitHub Copilot

URL mode:

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

Command mode (stdio-only clients):

{
  "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"
      }
    }
  }
}

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.

# 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

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:

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

---

Tools Reference (55 total)

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": "..." }

Paginated list responses wrap their items in a PagedResponse<T>:

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

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. |

---

Sessions (3 tools)

| Tool | Description | |---|---| | fetch_sessions | Paginated list of sessions with optional time range filter. | | get_session_details | Full session detail including all its traces. Requires sessionId. | | get_user_sessions | All sessions for a specific user with pagination. Requires userId. |

---

Prompts (5 tools)

| Tool | Description | |---|---| | list_prompts | Paginated list of all prompts in the project. | | get_prompt | Fetch a prompt by name. Optionally pin to a version number or a label (e.g. production, staging). | | create_prompt | Create a new prompt or append a new version to an existing prompt. type is text (plain string) or chat (JSON array of {role, content} messages). Supports comma-separated labels and tags. | | delete_prompt | Delete prompt versions by name. Scope to a specific label or version; omit both to delete all versions. Irreversible. | | update_prompt_labels | Replace the full label set on a specific prompt version. Supply an empty string to remove all labels. The latest label is reserved by Langfuse. |

---

Datasets (7 tools)

| Tool | Description | |---|---| | list_datasets | Paginated list of all evaluation datasets. | | get_dataset | Fetch a dataset by exact name. | | create_dataset | Create a new dataset. Optionally supply description, metadataJson, inputSchemaJson, and expectedOutputSchemaJson (all as JSON strings). | | list_dataset_items | Paginated list of items in a dataset. Requires datasetName. | | get_dataset_item | Fetch a single dataset item by ID. | | create_dataset_item | Create or upsert a dataset item. Optionally link to a sourceTraceId or sourceObservationId. Supports itemId for upsert semantics. | | delete_dataset_item | Permanently delete a dataset item by ID. Irreversible. |

---

Dataset Runs (5 tools)

| Tool | Description | |---|---| | list_dataset_runs | Paginated list of experiment runs for a dataset. Requires datasetName. | | get_dataset_run | Full run detail including all run items. Requires datasetName and runName. | | delete_dataset_run | Delete a run and all its items. Irreversible. Requires datasetName and runName. | | list_dataset_run_items | Paginated list of items in a run. Requires datasetId and runName. | | create_dataset_run_item | Create a run item linking a dataset item to a trace/observation. Creates the run automatically if it does not yet exist. |

---

Metrics (1 tool)

| Tool | Description | |---|---| | get_cost_metrics | Query Langfuse cost, token, latency, and usage analytics via the Metrics API v1. Mirrors: GET /api/public/metrics?query=<json>. Pass the full query as a JSON string. All aggregation is server-side. |

This tool accepts a single required parameter query which must be a JSON-serialised string matching the Metrics API schema. Examples (pass these as a single JSON string):

• Total cost last 7 days:

{"view":"traces","metrics":[{"measure":"totalCost","aggregation":"sum"}],"fromTimestamp":"2026-03-18T00:00:00Z","toTimestamp":"2026-03-25T23:59:59Z"}

• Daily cost trend this week:

{"view":"traces","metrics":[{"measure":"totalCost","aggregation":"sum"},{"measure":"count","aggregation":"count"}],"timeDimension":{"granularity":"day"},"fromTimestamp":"2026-03-18T00:00:00Z","toTimestamp":"2026-03-25T23:59:59Z"}

• Cost by model:

{"view":"observations","dimensions":[{"field":"providedModelName"}],"metrics":[{"measure":"totalCost","aggregation":"sum"},{"measure":"totalTokens","aggregation":"sum"}],"fromTimestamp":"2026-03-18T00:00:00Z","toTimestamp":"2026-03-25T23:59:59Z"}

• Cost for a specific user:

{"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"}

• Production environment only:

filters: [{"column":"environment","operator":"=","value":"production","type":"string"}]

---

Scores (6 tools)

| Tool | Description | |---|---| | get_scores | Paginated list of evaluation scores. Filter by traceId, observationId, name, dataType (NUMERIC\|CATEGORICAL\|BOOLEAN), and time range. | | get_score | Fetch a single score by ID. | | get_score_configs | Paginated list of score config schemas. | | get_score_config | Fetch a single score config by ID. | | create_score_config | Create a score config. NUMERIC supports optional minValue/maxValue. CATEGORICAL accepts a categoriesJson array of {label, value} objects. | | update_score_config | Update an existing score config. Optionally set isArchived to archive it. |

---

Annotation Queues (8 tools)

| Tool | Description | |---|---| | list_annotation_queues | Paginated list of annotation queues. | | get_annotation_queue | Fetch a single queue by ID. | | create_annotation_queue | Create a queue for human-in-the-loop review. Optionally link a scoreConfigId. | | list_annotation_queue_items | Paginated list of items in a queue. Optionally filter by status (PENDING\|COMPLETED). Requires queueId. | | get_annotation_queue_item | Fetch a specific queue item by queueId and itemId. | | create_annotation_queue_item | Add a trace, observation, or session to a queue for review. objectType is TRACE, OBSERVATION, or SESSION. | | update_annotation_queue_item | Update the status of a queue item (PENDING\|COMPLETED). | | delete_annotation_queue_item | Remove an item from a queue. Irreversible. |

---

Comments (3 tools)

| Tool | Description | |---|---| | get_comments | Paginated list of comments. Optionally filter by objectType (TRACE\|OBSERVATION) and objectId. | | get_comment | Fetch a single comment by ID. | | create_comment | Attach a comment to a trace, observation, session, or prompt. objectType values: TRACE, OBSERVATION, SESSION, PROMPT. |

---

Models (4 tools)

| Tool | Description | |---|---| | list_models | Paginated list of all model definitions (Langfuse-managed and custom). | | get_model | Fetch a model definition by ID. | | create_model | Create a custom model for cost tracking. Requires modelName, matchPattern (regex), and unit (TOKENS\|CHARACTERS\|MILLISECONDS\|SECONDS\|IMAGES\|REQUESTS). Optionally set per-unit USD prices. | | delete_model | Delete a custom model definition. Langfuse-managed models cannot be deleted. Irreversible. |

---

LLM Connections (2 tools)

| Tool | Description | |---|---| | list_llm_connections | Paginated list of LLM provider connections (secret keys are masked in the response). | | upsert_llm_connection | Create or update a provider connection by provider name (e.g. openai, anthropic, azure, google). Upserts by provider — if a connection already exists it is updated. |

---

Project (1 tool)

| Tool | Description | |---|---| | get_projects_for_api_key | Returns the project(s) visible to the configured API key. Useful for confirming credentials and project metadata. |

---

Users (1 tool)

| Tool | Description | |---|---| | get_user_traces | All traces for a specific Langfuse user ID with pagination. Requires userId. |

---

Schema (1 tool)

| Tool | Description | |---|---| | get_data_schema | Returns the full Langfuse data model: all entity types, fields, and valid enum values. Call this first to understand the available data structures before running queries. |

---

Architecture

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

The architecture is strictly layered:

• client/ — Langfuse integration boundary: HTTP with Basic-Auth (Apache HttpComponents 5), typed exceptions, UriComponentsBuilder for query params
• service/ — domain logic: filtering, mapping, pagination, error translation into ApiResponse
• tools/ — MCP surface: agent-friendly descriptions, parameter validation, delegation to services
• Spring Boot — runtime and transport wrapper only

API Client

LangfuseApiClient supports four HTTP methods. All methods throw LangfuseApiException or ResourceNotFoundException on error, which the service layer converts into structured ApiResponse.error(...) responses — agents never see raw stack traces.

| Method | Used for | |---|---| | GET | All read operations | | POST | Create operations | | PATCH | Update operations | | DELETE | Delete operations |

---

Package Structure

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)

---

Running Tests

mvn test

Test coverage includes:

• LangfusePropertiesBindingTest — config binding from application-test.yml and property-level validation
• PromptWriteServiceImplTest — service logic for prompt create / delete / label update
• ProjectServiceImplTest — project API response mapping
• ObservationServiceImplTest — observation fetch and field mapping
• MetricsServiceImplTest — metrics aggregation logic

Tests run with spring.ai.mcp.server.enabled=false (set in src/test/resources/application-test.yml) so no MCP transport is started during test execution.

---

Troubleshooting

TRACE_FETCH_ERROR: HTTP/1.1 header parser received no bytes

Connectivity issue — not a code bug. Check:

1. LANGFUSE_HOST points to a running Langfuse instance
2. The host is reachable from the JVM process
3. For Docker: use host.docker.internal instead of localhost
4. The scheme matches your server (http:// vs https://)
5. Confirm the API is up: curl $LANGFUSE_HOST/api/public/health

INVALID_INPUT: <param> is required

A required parameter was not provided. All required = true parameters are validated at the tool layer before any HTTP call is made.

Connection timeouts

Increase the timeout:

export LANGFUSE_TIMEOUT=60s

Agent cannot see the server

1. Confirm the server is running: curl http://localhost:8080/actuator/health
2. Confirm the MCP endpoint is reachable: curl http://localhost:8080/ping
3. Check that the client config URL points to http://localhost:8080/mcp
4. Inspect all available tools: npx @modelcontextprotocol/inspector http://localhost:8080/mcp

Langfuse-managed models cannot be deleted

delete_model only works for custom model definitions you have created. To override a Langfuse-managed model's pricing, create a new custom model with the same modelName.

---

License