Langfuse MCP

What avivsinai/langfuse-mcp MCP server does

The avivsinai/langfuse-mcp MCP server gives an MCP-compatible agent access to Langfuse telemetry and selected management operations. Its main debugging workflows cover traces, observations, sessions, exceptions, and routing decisions. An agent can locate recent exception groups, inspect the files and traces associated with them, retrieve trace observations, and examine session behavior.

The server also exposes tools for prompts, datasets, annotation queues, scores, metrics, and the Langfuse data schema. The README lists 48 tools in total. This makes the project suitable for agents that need to investigate LLM application behavior while also reading or updating selected Langfuse resources.

How it works

The server runs locally and uses the Langfuse Python SDK to access a Langfuse project. It can communicate with clients over local stdio or HTTP. The documented quick-start flow launches it with uvx langfuse-mcp, after which an MCP client can call its tools.

Tool groups can be selected at startup with the --tools option. Available groups include traces, observations, routing, sessions, exceptions, prompts, datasets, annotation queues, scores, metrics, and schema. Selective loading reduces the number of exposed tools and the associated context overhead.

The route-decision tools expect span observations containing the mcp.route_decision.v1 metadata schema. Metrics queries aggregate values such as cost, latency, token usage, counts, and score values on the server side. The v2 metrics endpoint is documented as Cloud-only, so self-hosted Langfuse deployments may return a 404 for those queries.

Setup and configuration

Install uv and use Python 3.10 or newer. Create Langfuse API credentials in Langfuse Cloud, or provide the URL of a self-hosted instance through LANGFUSE_HOST. The documented credentials are LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, and LANGFUSE_HOST.

A typical launch command is:

uvx langfuse-mcp

The project documents setup examples for Claude Code and Codex CLI, and states that it can be used with Cursor or another MCP client. Restarting the client and checking its MCP status verifies that the process is available.

For safer access, start the avivsinai/langfuse-mcp MCP server with --read-only, or set LANGFUSE_MCP_READ_ONLY=true. This disables documented write operations, including prompt creation, prompt label updates, dataset changes, and annotation queue changes.

Tools and capabilities

Key tool groups include:

• Trace and observation retrieval with fetch_traces, fetch_trace, fetch_observations, and fetch_observation.
• Exception discovery and inspection with find_exceptions, find_exceptions_in_file, get_exception_details, and get_error_count.
• Session analysis through session listing, session details, and user-session lookup tools.
• Route-decision search, retrieval, summarization, and low-confidence filtering.
• Prompt listing, retrieval, creation, and label updates.
• Dataset, dataset-run, annotation-queue, score, metrics, and schema operations.

Dataset item creation behaves as an upsert: supplying an existing item ID updates that item, while a new ID creates one. Exception discovery first returns grouped results; a follow-up file search is needed to obtain trace IDs for detailed inspection.

Limitations and notes

This local server is positioned for debugging and selected Langfuse operations, not as a complete replacement for Langfuse's hosted native MCP endpoint. The README specifically notes that score writes, comments, models, and media are not provided here, while the native hosted service supports those areas.

Write-capable tools are available unless read-only mode is enabled, so deployments that only need investigation should use that setting. Metrics dimensions should not contain high-cardinality fields such as IDs; those belong in filters. The server requires valid Langfuse credentials and a reachable Langfuse deployment, and self-hosted users should verify feature availability such as the v2 metrics endpoint.