fetch_tracesLABSCO SUMMARY
The write half of Langfuse, which the official server does not expose.
The README's comparison table is the argument: traces, sessions, exceptions, datasets, scores, annotation queues, comments and model definitions are all absent from the official Langfuse MCP, and prompt access there is read-only. That makes this the option when the loop you want is find the failing traces, add them to a review queue, then ship a new prompt version — all without a browser. Pagination is one-based, limits default to 20, and several tools delete permanently, so read the annotations before auto-approving anything.
What it is
A Spring Boot MCP server that puts the Langfuse public REST API in front of an agent over Streamable HTTP. It goes well past reading traces: prompts can be created and relabelled, datasets and experiment runs managed, score configs defined, annotation queues filled for human review, and custom cost models registered.
What you get
- Trace work, including the error path:
fetch_traceswith filters on user, session, tags and time;find_exceptionsfor ERROR-level traces;find_exceptions_in_filefor errors whose metadata names a given file;get_error_countover a window - Session and user views —
fetch_sessions,get_session_detailswith all its traces,get_user_sessions,get_user_traces - Prompt management in both directions:
list_prompts,get_promptpinned to a version or a label such as production,create_prompt,delete_prompt,update_prompt_labels - Evaluation plumbing — datasets and items, dataset runs and run items, plus scores and score configs including numeric ranges and categorical label sets
create_annotation_queueand its item tools, so a trace, observation or session can be pushed to a human reviewer from the same conversationget_cost_metrics, which takes a JSON query against the Metrics API and aggregates cost, tokens, latency and usage server-sideget_data_schema, which returns the full Langfuse data model and is the one to call first- Destructive counterparts exist and are marked as irreversible:
delete_trace,delete_traces,delete_dataset_item,delete_dataset_run,delete_model
Requirements
A Langfuse account and an API key pair: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY and LANGFUSE_HOST are all required, and LANGFUSE_TIMEOUT defaults to 30s. Java 21 or later plus Maven 3.9+, or the multi-stage Dockerfile which compiles inside Docker. Build produces langfuse-mcp-1.0.0.jar; the server listens on port 8080 and the MCP endpoint is /mcp — the legacy SSE path is not used. Self-hosted Langfuse works by pointing the host at your instance. MIT licensed.
Setup effort
Build from source — git clone https://github.com/Log-LogN/langfuse-mcp-java.git
USE CASES
01
Finding out what broke in production last night
List ERROR-level traces over the window, count them, then open one in full with its nested observations, inputs, outputs and token usage.
02
Tracing a single user's bad session
Pull that user's sessions, open the one that went wrong, and read every trace it contains in order.
03
Shipping a prompt change
Read the current production version, append a new one, then move the production label onto it once it looks right.
04
Turning a real failure into a test case
Create a dataset item from the trace that failed, link it back to the source trace, and record the run item against an experiment.
05
Queueing outputs for human review
Create a queue bound to a score config, add the traces that need judgement, and mark items completed as reviewers work through them.
06
Answering where the money went
Query cost and token totals grouped by model over a date range, with aggregation done server-side rather than by pulling raw traces.
55 tools
Listed in project docs. Your client may show a different list.
fetch_tracefind_exceptionsfind_exceptions_in_fileget_exception_detailsget_error_countdelete_tracedelete_tracesfetch_sessionsget_session_detailsget_user_sessionslist_promptsget_promptcreate_promptdelete_promptupdate_prompt_labelslist_datasetsget_datasetcreate_datasetlist_dataset_itemsget_dataset_itemcreate_dataset_itemdelete_dataset_itemlist_dataset_runsget_dataset_rundelete_dataset_runlist_dataset_run_itemscreate_dataset_run_itemget_cost_metricsget_scoresget_scoreget_score_configsget_score_configcreate_score_configupdate_score_configlist_annotation_queuesget_annotation_queuecreate_annotation_queuelist_annotation_queue_itemsget_annotation_queue_itemcreate_annotation_queue_itemupdate_annotation_queue_itemdelete_annotation_queue_itemget_commentsget_commentcreate_commentlist_modelsget_modelcreate_modeldelete_modellist_llm_connectionsupsert_llm_connectionget_projects_for_api_keyget_user_tracesget_data_schemaBEFORE YOU INSTALL
What to know first
Tools you get
55 tools named in the project's documentation. The langfuse.read-only setting restricts nothing: 20 of the 55 tools create, update or delete, and all seven deletes, delete_trace and delete_prompt among them, are documented as irreversible.
Requires
- Java 21 or later
- Maven 3.9+
- LANGFUSE_PUBLIC_KEY in your environment
- LANGFUSE_SECRET_KEY in your environment
INSTALLATION
Connect your client
This one is built from source rather than installed with a single command.
Server setup
TERMINAL
git clone https://github.com/Log-LogN/langfuse-mcp-java.git
cd langfuse-mcp-java
# 1. Build
mvn clean package -DskipTests
# 2. Set credentials
export LANGFUSE_PUBLIC_KEY=<YOUR_LANGFUSE_PUBLIC_KEY>
export LANGFUSE_SECRET_KEY=<YOUR_LANGFUSE_SECRET_KEY>
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/mcpMCP Clients
Cursor
CURSOR · JSON
{
"mcpServers": {
"langfuse": {
"url": "http://localhost:8080/mcp"
}
}
}GitHub Copilot in VS Code — HTTP
GITHUB COPILOT IN VS CODE — HTTP · JSON
{
"servers": {
"langfuse": {
"url": "http://localhost:8080/mcp"
}
}
}GitHub Copilot in VS Code — stdio
GITHUB COPILOT IN VS CODE — STDIO · JSON
{
"servers": {
"langfuse": {
"command": "java",
"args": [
"-jar",
"<YOUR_PATH_TO_LANGFUSE_MCP_1_0>"
],
"env": {
"LANGFUSE_PUBLIC_KEY": "<YOUR_LANGFUSE_PUBLIC_KEY>",
"LANGFUSE_SECRET_KEY": "<YOUR_LANGFUSE_SECRET_KEY>",
"LANGFUSE_HOST": "https://cloud.langfuse.com"
}
}
}
}Other routes
Run with Docker
RUN WITH DOCKER · TERMINAL
git clone https://github.com/Log-LogN/langfuse-mcp-java.git
cd langfuse-mcp-javaBuild image (compiles inside Docker, no local Maven needed):
RUN WITH DOCKER · TERMINAL
docker build -t langfuse-mcp:latest .Then run it
RUN WITH DOCKER · TERMINAL
docker run --rm -p 8080:8080 \
-e LANGFUSE_PUBLIC_KEY=<YOUR_LANGFUSE_PUBLIC_KEY> \
-e LANGFUSE_SECRET_KEY=<YOUR_LANGFUSE_SECRET_KEY> \
-e LANGFUSE_HOST=https://cloud.langfuse.com \
langfuse-mcp:latest
