# Langfuse MCP Setup Reference
Detailed setup instructions, troubleshooting, and configuration options.
## Manual .mcp.json Setup
If you prefer manual configuration over `claude mcp add`:
```json
{
"mcpServers": {
"langfuse": {
"command": "uvx",
"args": ["--python", "3.11", "langfuse-mcp"],
"env": {
"LANGFUSE_PUBLIC_KEY": "pk-...",
"LANGFUSE_SECRET_KEY": "sk-...",
"LANGFUSE_HOST": "https://cloud.langfuse.com"
}
}
}
}
```
**Important:** If `.mcp.json` already exists, merge the `langfuse` entry into the existing `mcpServers` object. Don't overwrite the file.
### Add to .gitignore
```bash
grep -q '.mcp.json' .gitignore 2>/dev/null || echo '.mcp.json' >> .gitignore
```
Never commit credentials to version control.
---
## Troubleshooting
### Authentication Errors
- Public key must start with `pk-`
- Secret key must start with `sk-`
- Host must match your Langfuse instance (cloud vs self-hosted)
### Python Version Errors
If MCP fails to connect, check your Python version. The Langfuse SDK requires Python 3.13 or earlier (due to Pydantic v1 dependency).
Fix by pinning Python in the uvx command:
```bash
uvx --python 3.11 langfuse-mcp
```
Or verify manually:
```bash
uvx --python 3.11 langfuse-mcp --help
```
### Timeout Errors
Increase the timeout:
```bash
# Claude Code with timeout
claude mcp add \
--scope project \
--env LANGFUSE_PUBLIC_KEY=pk-... \
--env LANGFUSE_SECRET_KEY=sk-... \
--env LANGFUSE_HOST=https://cloud.langfuse.com \
langfuse -- uvx --python 3.11 langfuse-mcp --timeout 60
# Or in .mcp.json
"args": ["--python", "3.11", "langfuse-mcp", "--timeout", "60"]
```
### Empty Results
- Check `age` parameter (minutes, not hours/days)
- Verify filters match your data
- Try `fetch_traces(age=1440)` with no filters to confirm data exists
- Data older than 7 days (10080 minutes) cannot be retrieved
### MCP Not Found
- Restart Claude Code / Codex CLI after adding MCP
- Run `/mcp` (Claude) or `codex mcp list` (Codex) to verify
- Check `.mcp.json` syntax (valid JSON, correct paths)
- Codex CLI uses `~/.codex/config.toml` for config; verify that file instead of `.mcp.json`
---
## Date-to-Minutes Conversion
| Time Range | Minutes |
|------------|---------|
| 1 hour | 60 |
| 6 hours | 360 |
| 12 hours | 720 |
| 1 day | 1440 |
| 2 days | 2880 |
| 3 days | 4320 |
| 7 days | 10080 (max) |
---
## Glossary
| Term | Definition |
|------|------------|
| **Trace** | Top-level container for a user interaction/request |
| **Observation** | Span, generation, or event inside a trace |
| **Generation** | LLM API call with input/output/tokens/latency |
| **Span** | Timed operation (function call, API request) |
| **Event** | Discrete log entry or exception |
| **Session** | Group of traces from the same user session |
---
## Tool Groups
Load specific tool groups to reduce token overhead:
```bash
langfuse-mcp --tools traces,prompts
```
| Group | Tools |
|-------|-------|
| `traces` | fetch_traces, fetch_trace |
| `observations` | fetch_observations, fetch_observation |
| `sessions` | fetch_sessions, get_session_details, get_user_sessions |
| `exceptions` | find_exceptions, find_exceptions_in_file, get_exception_details, get_error_count |
| `prompts` | list_prompts, get_prompt, get_prompt_unresolved, create_text_prompt, create_chat_prompt, update_prompt_labels |
| `schema` | get_data_schema |
---
## Environment Variables
| Variable | Description |
|----------|-------------|
| `LANGFUSE_PUBLIC_KEY` | API public key (starts with `pk-`) |
| `LANGFUSE_SECRET_KEY` | API secret key (starts with `sk-`) |
| `LANGFUSE_HOST` | Langfuse instance URL |
| `LANGFUSE_TIMEOUT` | API timeout in seconds (default: 30) |
| `LANGFUSE_MCP_TOOLS` | Comma-separated tool groups to load |
| `LANGFUSE_MCP_LOG_FILE` | Log file path (default: `/tmp/langfuse_mcp.log`) |
| `LANGFUSE_MCP_READ_ONLY` | Set to `true` to disable write tools (safer observability mode) |
---
## Skill Installation Scopes
| Scope | Claude Code | Codex CLI |
|-------|-------------|-----------|
| Project | `.claude/skills/langfuse/` | `.codex/skills/langfuse/` |
| User/Global | `~/.claude/skills/langfuse/` | `~/.codex/skills/langfuse/` |
Install globally:
```bash
cp -r skills/langfuse ~/.claude/skills/ # Claude Code
cp -r skills/langfuse ~/.codex/skills/ # Codex CLI
```
---
## Security Notes
- Never commit `.mcp.json` with real credentials
- Rotate keys if leaked
- `full_json_file` exports may contain sensitive user data
- Use environment variable injection in CI/CD rather than hardcoded values
