# log-logn/langfuse-mcp-java [Health: Active]

**Category:** 📊 Monitoring  
**Repository:** https://github.com/Log-LogN/langfuse-mcp-java  
**GitHub Stars:** 3  
**npm Downloads (last month):** 1014756  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/log-logn-langfuse-mcp-java

## Description
Query Langfuse traces, debug exceptions, analyze sessions, scores, datasets, schema, observations and manage prompts. Full observability toolkit for LLM applications. (https://github.com/langfuse/langfuse)

## Tools
Capabilities this server exposes over MCP:

- **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.
- **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`.
- **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.
- **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.
- **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.
- **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.
- **get_scores** — Paginated list of evaluation scores. Filter by `traceId`, `observationId`, `name`, `dataType` (`NUMERIC`\
- **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.
- **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`\
- **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`\
- **delete_annotation_queue_item** — Remove an item from a queue. **Irreversible.
- **get_comments** — Paginated list of comments. Optionally filter by `objectType` (`TRACE`\
- **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`.
- **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`\
- **delete_model** — Delete a custom model definition. Langfuse-managed models cannot be deleted. **Irreversible.
- **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.
- **get_projects_for_api_key** — Returns the project(s) visible to the configured API key. Useful for confirming credentials and project metadata.
- **get_user_traces** — All traces for a specific Langfuse user ID with pagination. Requires `userId`.
- **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.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "langfuse-mcp-java": {
    "command": "npx",
    "args": ["-y","@modelcontextprotocol/inspector"],
    "env": {
      "LANGFUSE_PUBLIC_KEY": "",
      "LANGFUSE_SECRET_KEY": "",
      "LANGFUSE_HOST": "",
      "LANGFUSE_TIMEOUT": ""
    }
  }
}
```

**Requires environment variables:** `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_HOST`, `LANGFUSE_TIMEOUT` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

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

_Full upstream README: https://allmcps.com/mcp/log-logn-langfuse-mcp-java/readme_