Langfuse MCP (Model Context Protocol)

What is Langfuse MCP?

Langfuse MCP is an agent-facing Model Context Protocol server and skill for Langfuse observability. It lets AI agents query traces, inspect generations, debug exceptions, analyze sessions, manage prompts, browse datasets, and understand what agents did in production.

How to use Langfuse MCP?

Install via uvx langfuse-mcp with Python 3.10+ and the uv runtime. Set environment variables LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, and LANGFUSE_HOST (defaults to Langfuse Cloud). Add the server to an MCP client (Claude Code, Codex, Cursor) using the provided configuration commands or JSON files. Start the MCP client, then invoke tools directly or use the included agent skill for ready‑made debugging playbooks.

Key features of Langfuse MCP

• 48 tools covering traces, observations, sessions, exceptions, prompts, datasets, annotation queues, scores, metrics, and schema.
• Selective tool loading via --tools flag to reduce token overhead.
• Read‑only mode (--read-only) disables all write operations.
• Default output mode (--default-output-mode) for compact, full JSON string, or file output.
• Support for HTTP transport with per‑project credentials via Authorization header.
• Included agent skill with playbooks for trace debugging, exception triage, latency analysis, prompt management, and dataset work.

Use cases of Langfuse MCP

• Debug failing agent runs by querying Langfuse traces and observations.
• Find exceptions, slow generations, high‑latency spans, and affected users.
• Inspect sessions and user journeys without leaving the agent workflow.
• Manage prompt versions, labels, datasets, annotation queues, and scores.
• Answer questions like “what failed?”, “why was this slow?”, or “which prompt version ran?”

FAQ from Langfuse MCP

How does Langfuse MCP differ from the native Langfuse MCP?

Langfuse MCP is a local, debugging‑first server with compact trace inspection, exception triage, session analysis, and route‑decision tools. It does not mirror every native MCP tool; the native MCP is a hosted endpoint with a broader API surface.

What are the runtime requirements?

Python 3.10–3.14 and the uv package runner (for uvx). The server is verified on CI for those Python versions.

Can I load only specific tools?

Yes. Use langfuse-mcp --tools traces,prompts to load only the tool groups you need. Available groups include traces, observations, routing, sessions, exceptions, prompts, datasets, annotation_queues, scores, metrics, and schema.

Is there a read‑only mode?

Yes. Start with langfuse-mcp --read-only or set LANGFUSE_MCP_READ_ONLY=true to disable all write operations (e.g., creating prompts, datasets, annotation queue items).

How do I use Langfuse MCP with multiple Langfuse projects?

Run the server in HTTP transport mode with --transport streamable-http. Each MCP client passes its project credentials as a Basic Authorization header (base64(public_key:secret_key)). An absent header falls back to the server’s startup environment credentials.