Langfuse MCP Guide 🚀

🚀 Quick Start One-liner for Claude Code to instantly attach the server using npx. Set your keys directly in the command.

claude mcp add langfuse -e LANGFUSE_PUBLIC_KEY=pk-lf-... -e LANGFUSE_SECRET_KEY=sk-lf-... -- npx -y langfuse-mcp-extended

🔧 Configuration Requires LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY environment variables. Optional variables include LANGFUSE_BASE_URL (defaults to US Cloud, configure for EU/Self-hosted) and LOG_LEVEL.

{
  "mcpServers": {
    "langfuse-observability": {
      "command": "npx",
      "args": ["-y", "langfuse-mcp-extended"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-...",
        "LANGFUSE_SECRET_KEY": "sk-lf-...",
        "LANGFUSE_BASE_URL": "https://eu.cloud.langfuse.com"
      }
    }
  }
}

📦 Dependencies

• Target: langfuse-mcp-extended (Community extension by JaviMaligno).
• Capabilities: 22 tools exposing Traces, Observations, Scores, Score Configs, Datasets, and Sessions.

💡 Best Practices / Patterns

• Dual Server Strategy: Use langfuse-mcp-extended strictly for deep observability (traces, scores, datasets). Use the official Langfuse built-in MCP server for prompt management.
• Response Size Control: Keep includeIO=false (the default) on getTrace, getSession, and getObservation to strip massive input/output fields. Only set includeIO=true when the exact payload is necessary to avoid context window saturation.
• Granular Fetching: Avoid blind bulk list requests. Always provide explicit traceId, observationId, or time ranges.
• Diagnostic Triage: Treat traces as the starting point for root-cause analysis. Pull linked observations and metrics to deduce the exact point of failure (e.g., context saturation vs. retrieval lag).
• Read-Only Agent Scoping: In sensitive environments, restrict the LLM to only list* and get* operations. This prevents rogue agents from creating, modifying, or deleting scores and datasets.

🚨 Gotchas / Anti-patterns

• Native Redundancy Warning: As of late May 2026, Langfuse expanded its official native server to cover most observability features. Verify if the official server meets your needs before adding this third-party dependency.
• Context Window Bloat: Blindly calling listTraces or querying long traces without specific filters will immediately bloat and crash the LLM context.
• Tool Schema Injection: Refrain from manually passing or pasting tool schemas into agent prompt history. This is known to corrupt Langfuse Playground replays.
• Token Passthrough: Never pass raw user tokens or secrets directly through the MCP queries. Ensure credentials are strictly scoped to the accessed Langfuse project.
• Local Routing Traps: If running self-hosted Langfuse locally via stdio transport, ensure firewall and network configs allow the MCP server to reach the Langfuse API.

🔍 Research / References

• GitHub Repository: JaviMaligno/langfuse-mcp-server
• NPM Package: langfuse-mcp-extended
• Official Counterpart: Langfuse Official MCP Docs
• Active Integration Discussions: langfuse/langfuse#5646