Langfuse MCP Server

1---
2name: langfuse
3version: 1.0.2
4description: Debug AI traces, find exceptions, analyze sessions, and manage prompts via Langfuse MCP. Also handles MCP setup and configuration.
5metadata:
6  short-description: Langfuse observability via MCP
7  compatibility: claude-code, codex-cli
8---
9 
10# Langfuse Skill
11 
12Debug your AI systems through Langfuse observability.
13 
14**Triggers:** langfuse, traces, debug AI, find exceptions, set up langfuse, what went wrong, why is it slow, datasets, evaluation sets
15 
16## Setup
17 
18**Step 1:** Get credentials from https://cloud.langfuse.com → Settings → API Keys
19 
20If self-hosted, use your instance URL for `LANGFUSE_HOST` and create keys there.
21 
22**Step 2:** Install MCP (pick one):
23 
24```bash
25# Claude Code (project-scoped, shared via .mcp.json)
26claude mcp add \
27  --scope project \
28  --env LANGFUSE_PUBLIC_KEY=pk-... \
29  --env LANGFUSE_SECRET_KEY=sk-... \
30  --env LANGFUSE_HOST=https://cloud.langfuse.com \
31  langfuse -- uvx --python 3.11 langfuse-mcp
32 
33# Codex CLI (user-scoped, stored in ~/.codex/config.toml)
34codex mcp add langfuse \
35  --env LANGFUSE_PUBLIC_KEY=pk-... \
36  --env LANGFUSE_SECRET_KEY=sk-... \
37  --env LANGFUSE_HOST=https://cloud.langfuse.com \
38  -- uvx --python 3.11 langfuse-mcp
39```
40 
41**Step 3:** Restart CLI, verify with `/mcp` (Claude) or `codex mcp list` (Codex)
42 
43**Step 4:** Test: `fetch_traces(age=60)`
44 
45### Read-Only Mode
46 
47For safer observability without risk of modifying prompts or datasets, enable read-only mode:
48 
49```bash
50# CLI flag
51langfuse-mcp --read-only
52 
53# Or environment variable
54LANGFUSE_MCP_READ_ONLY=true
55```
56 
57This disables write tools: `create_text_prompt`, `create_chat_prompt`, `update_prompt_labels`, `create_dataset`, `create_dataset_item`, `delete_dataset_item`.
58 
59For manual `.mcp.json` setup or troubleshooting, see `references/setup.md`.
60 
61---
62 
63## Playbooks
64 
65### "Where are the errors?"
66 
67```
68find_exceptions(age=1440, group_by="file")
69```
70→ Shows error counts by file. Pick the worst offender.
71 
72```
73find_exceptions_in_file(filepath="src/ai/chat.py", age=1440)
74```
75→ Lists specific exceptions. Grab a trace_id.
76 
77```
78get_exception_details(trace_id="...")
79```
80→ Full stacktrace and context.
81 
82---
83 
84### "What happened in this interaction?"
85 
86```
87fetch_traces(age=60, user_id="...")
88```
89→ Find the trace. Note the trace_id.
90 
91If you don't know the user_id, start with:
92```
93fetch_traces(age=60)
94```
95 
96```
97fetch_trace(trace_id="...", include_observations=true)
98```
99→ See all LLM calls in the trace.
100 
101```
102fetch_observation(observation_id="...")
103```
104→ Inspect a specific generation's input/output.
105 
106---
107 
108### "Why is it slow?"
109 
110```
111fetch_observations(age=60, type="GENERATION")
112```
113→ Find recent LLM calls. Look for high latency.
114 
115```
116fetch_observation(observation_id="...")
117```
118→ Check token counts, model, timing.
119 
120---
121 
122### "What's this user experiencing?"
123 
124```
125get_user_sessions(user_id="...", age=1440)
126```
127→ List their sessions.
128 
129```
130get_session_details(session_id="...")
131```
132→ See all traces in the session.
133 
134---
135 
136### "Manage datasets"
137 
138```
139list_datasets()
140```
141→ See all datasets.
142 
143```
144get_dataset(name="evaluation-set-v1")
145```
146→ Get dataset details.
147 
148```
149list_dataset_items(dataset_name="evaluation-set-v1", page=1, limit=10)
150```
151→ Browse items in the dataset.
152 
153```
154create_dataset(name="qa-test-cases", description="QA evaluation set")
155```
156→ Create a new dataset.
157 
158```
159create_dataset_item(
160  dataset_name="qa-test-cases",
161  input={"question": "What is 2+2?"},
162  expected_output={"answer": "4"}
163)
164```
165→ Add test cases.
166 
167```
168create_dataset_item(
169  dataset_name="qa-test-cases",
170  item_id="item_123",
171  input={"question": "What is 3+3?"},
172  expected_output={"answer": "6"}
173)
174```
175→ Upsert: updates existing item by id or creates if missing.
176 
177---
178 
179### "Manage prompts"
180 
181```
182list_prompts()
183```
184→ See all prompts with labels.
185 
186```
187get_prompt(name="...", label="production")
188```
189→ Fetch current production version.
190 
191```
192create_text_prompt(name="...", prompt="...", labels=["staging"])
193```
194→ Create new version in staging.
195 
196```
197update_prompt_labels(name="...", version=N, labels=["production"])
198```
199→ Promote to production. (Rollback = re-apply label to older version)
200 
201---
202 
203## Quick Reference
204 
205| Task | Tool |
206|------|------|
207| List traces | `fetch_traces(age=N)` |
208| Get trace details | `fetch_trace(trace_id="...", include_observations=true)` |
209| List LLM calls | `fetch_observations(age=N, type="GENERATION")` |
210| Get observation | `fetch_observation(observation_id="...")` |
211| Error count | `get_error_count(age=N)` |
212| Find exceptions | `find_exceptions(age=N, group_by="file")` |
213| List sessions | `fetch_sessions(age=N)` |
214| User sessions | `get_user_sessions(user_id="...", age=N)` |
215| List prompts | `list_prompts()` |
216| Get prompt | `get_prompt(name="...", label="production")` |
217| List datasets | `list_datasets()` |
218| Get dataset | `get_dataset(name="...")` |
219| List dataset items | `list_dataset_items(dataset_name="...", limit=N)` |
220| Create/update dataset item | `create_dataset_item(dataset_name="...", item_id="...")` |
221 
222`age` = minutes to look back (max 10080 = 7 days)
223 
224---
225 
226## References
227 
228- `references/tool-reference.md` — Full parameter docs, filter semantics, response schemas
229- `references/setup.md` — Manual setup, troubleshooting, advanced configuration
230