Langfuse-mcp-server

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.

- Java 21or later
- Maven 3.9+(or use the Docker build — no local Maven required)
- ALangfuseaccount with an API key pair (public-key+secret-key)

# 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 fromLangfuse Cloud→ Settings → API Keys.
Self-hosted Langfuse? SetLANGFUSE_HOSTto your instance URL.

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

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

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

{ "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/sseendpoint is not used by this server.

TheDockerfileis a multi-stage build: it compiles the Spring Boot jar inside Docker and runs the MCP server on port8080. 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

Langfuse running in another container on the same host:

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

Every tool returns a consistentApiResponse<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 aPagedResponse<T>:

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

Pagination is 1-based (pagedefaults to1).limitdefaults to20and is capped at100where noted. To page through results, incrementpagewhile keepinglimitfixed.

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

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

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

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

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

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

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

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

LangfuseApiClientsupports four HTTP methods. All methods throwLangfuseApiExceptionorResourceNotFoundExceptionon error, which the service layer converts into structuredApiResponse.error(...)responses — agents never see raw stack traces.

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)

- LangfusePropertiesBindingTest— config binding fromapplication-test.ymland 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 withspring.ai.mcp.server.enabled=false(set insrc/test/resources/application-test.yml) so no MCP transport is started during test execution.

TRACE_FETCH_ERROR: HTTP/1.1 header parser received no bytes

Connectivity issue — not a code bug. Check:
- LANGFUSE_HOSTpoints to a running Langfuse instance
- The host is reachable from the JVM process
- For Docker: usehost.docker.internalinstead oflocalhost
- The scheme matches your server (http://vshttps://)
- Confirm the API is up:curl $LANGFUSE_HOST/api/public/health

INVALID_INPUT: <param> is required

A required parameter was not provided. Allrequired = trueparameters are validated at the tool layer before any HTTP call is made.
- Confirm the server is running:curl http://localhost:8080/actuator/health
- Confirm the MCP endpoint is reachable:curl http://localhost:8080/ping
- Check that the client config URL points tohttp://localhost:8080/mcp
- Inspect all available tools:npx @modelcontextprotocol/inspector http://localhost:8080/mcp

Langfuse-managed models cannot be deleted

delete_modelonly works for custom model definitions you have created. To override a Langfuse-managed model's pricing, create a new custom model with the samemodelName.

Behavioral trust scoring for 14,820+ MCP servers. Check reliability, latency, and success rates before tool calls.

Structural observability for AI conversations. Detects loops, stuck states, and convergence patterns across 17 channels without analyzing content.

Paid remote MCP for AI agent run monitoring, failure detection, tool-call incident replay, SLA receipts, and client status exports.

An MCP server for fetching conversation history and prompts from the LangSmith observability platform.

Track AI agent costs, detect waste, optimize models, and prove ROI. 23 MCP tools for LLM cost tracking, provider arbitrage, budget enforcement, and revenue attribution.

Multi-Agent Monitoring LangFuse MCP Server

A Model Context Protocol (MCP) server for comprehensive monitoring and observability of multi-agent systems using Langfuse.

Behavioral trust layer for the AI agent economy. Check MCP server reliability scores, report interactions, detect anomalies, and discover the most trusted servers. 8 tools, free, real-time.

Guardrails service for AI agents. Default-deny tool call evaluation with LLM safety analysis, priority-ordered decision matrix, and human-in-the-loop escalations. Session recording, behavioral analysis, MCP proxy, secret redaction, and real-time audit.

Expose data observability, lineage, test results & incidents to AI agents via MCP

Provides access to OpenTelemetry traces and metrics through Logfire.