langfuse

Langfuse MCP Server

Agent-facing Model Context Protocol server and skill for Langfuse observability.

Use langfuse-mcp from Claude Code, Codex, Cursor, or any MCP client to query traces, inspect generations, debug exceptions, analyze sessions, manage prompts, browse datasets, and understand what your AI agents did in production.

What You Can Do

• Debug failing agent runs from Langfuse traces and observations.
• Find exceptions, slow generations, high-latency spans, and affected users.
• Inspect sessions and user journeys without leaving your agent workflow.
• Manage prompt versions, labels, datasets, annotation queues, and scores.
• Install the included langfuse agent skill for ready-made debugging playbooks.

Project Links

• Quick Start
• Agent Skill
• Tools
• Selective Tool Loading
• Read-Only Mode
• Other Clients

Why langfuse-mcp?

Langfuse is where your traces live. langfuse-mcp makes that telemetry directly usable by agents that need to answer questions like "what failed?", "why was this slow?", "which prompt version ran?", or "what happened in this user's session?"

Positioning relative to the native Langfuse MCP (as of June 2026):

	langfuse-mcp	Native Langfuse MCP
Primary fit	Local, debugging-first MCP server + agent skill	Hosted, zero-install endpoint backed by Langfuse
Deployment	Local stdio or HTTP, via the Langfuse Python SDK	Native streamable HTTP at /api/public/mcp
Trace / session / exception tools	First-class	Observation/API-oriented access
Route-decision tools	Yes	No
Token & output control	Compact summaries, truncation, file-dump mode, tool-group gating	Depends on the hosted tool response + client
Metrics & dataset runs	Yes	Yes
Prompt, dataset, queue & score reads	Yes	Yes
Score writes, comments, models, media	Not yet	Yes

This project does not mirror every native Langfuse MCP tool. It focuses on agent debugging ergonomics — compact trace inspection, exception triage, session analysis, routing-decision workflows, local tool-group gating, and an included skill with ready-made investigation playbooks. Use the native MCP for the broad hosted API surface; use langfuse-mcp as a local, token-disciplined layer.

Quick Start

Requires uv (for uvx) and Python 3.10 or newer. CI verifies Python 3.10 through 3.14.

Get credentials from Langfuse Cloud → Settings → API Keys. If self-hosted, use your instance URL for LANGFUSE_HOST.

# Claude Code (project-scoped, shared via .mcp.json)
claude mcp add \
  -e LANGFUSE_PUBLIC_KEY=pk-... \
  -e LANGFUSE_SECRET_KEY=sk-... \
  -e LANGFUSE_HOST=https://cloud.langfuse.com \
  --scope project \
  langfuse -- uvx langfuse-mcp

# Codex CLI (user-scoped, stored in ~/.codex/config.toml)
codex mcp add langfuse \
  --env LANGFUSE_PUBLIC_KEY=pk-... \
  --env LANGFUSE_SECRET_KEY=sk-... \
  --env LANGFUSE_HOST=https://cloud.langfuse.com \
  -- uvx langfuse-mcp

To pin a CI-verified interpreter explicitly, add --python 3.14 before langfuse-mcp.

Restart your CLI, then verify with /mcp (Claude Code) or codex mcp list (Codex).

Agent Skill

This repo ships a first-party langfuse skill for Claude Code and Codex. The skill gives agents concrete playbooks for trace debugging, exception triage, latency analysis, prompt management, and dataset work.

Install it when you want the agent to know when to reach for Langfuse and which MCP tools to call first.

Via skills (recommended):

npx skills add avivsinai/langfuse-mcp -g -y

Via skild:

npx skild install @avivsinai/langfuse -t claude -y

Manual install:

cp -r skills/langfuse ~/.claude/skills/   # Claude Code
cp -r skills/langfuse ~/.codex/skills/    # Codex CLI

After installing the skill, try:

help me debug langfuse traces
find exceptions in the last day
why was this user's session slow?