langfuse-mcp
You can use this local Langfuse MCP server to debug LLM traces, sessions, exceptions, prompts, datasets, metrics, and routing decisions through an MCP client.
Fetch and inspect traces and observations, with optional full observations and compact/file-dump output modes.
Browse sessions and user sessions, including detailed session data and observations.
Find, group, and inspect exceptions and error-level observations.
Analyze router route decisions, including low-confidence or uncallable decisions.
List, fetch, create, and label text/chat prompts.
Manage datasets, dataset items, dataset runs, and run items.
Manage annotation queues, queue items, and queue assignments.
Read scores and run aggregated metrics queries for cost, latency, tokens, counts, and score values.
Retrieve Langfuse trace/span/event schema and metrics schema information.
Operate read-only, load selective tool groups, and use local stdio or HTTP transport with per-project credentials.
Langfuse MCP Server
Usage: 12,518 PyPI downloads last month (pypistats, 2026-08-19). v0.10.1.
Local MCP server and skill for Langfuse. Debug traces, sessions, and exceptions from Claude Code, Codex, Cursor, or any MCP client.
Why this instead of native Langfuse MCP?
Use this for local debug: first-class traces, sessions, and exceptions; route-decision tools; compact / file-dump output; plus the included langfuse skill.
Use official Langfuse MCP for hosted, zero-install access to the broader API (score writes, comments, models, media).
As of June 2026:
langfuse-mcp | Native Langfuse MCP | |
Primary fit | Local debug: traces, sessions, exceptions | Hosted, zero-install API surface |
Deployment | Local | Native streamable HTTP at |
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 | Hosted tool response + client |
Metrics & dataset runs | Yes | Yes |
Prompt, dataset, queue & score reads | Yes | Yes |
Score writes, comments, models, media | No | Yes |
langfuse-mcp for local debug. Native MCP for hosted breadth.
Related MCP server: langfuse-mcp-extended
See a failing trace in 2 minutes
Install is uvx langfuse-mcp plus Langfuse API keys — Quick Start for Claude Code, Codex, Cursor, or Docker.
After the client restarts, ask:
find exceptions in the last dayThat maps to existing tools:
find_exceptions(age=1440, group_by="file")
find_exceptions_in_file(filepath="<file from the grouping>", age=1440)
get_exception_details(trace_id="<trace_id from the file results>")find_exceptions returns {group, count, observation_id, trace_id} (top 50 groups) — each group carries a representative observation/trace ID, and find_exceptions_in_file also yields full error records. Then optionally:
fetch_trace(trace_id="<trace_id>", include_observations=true)The exception tools detect errors by observation level == "ERROR" (strict; a non-empty status_message alone does not count). Counts describe error-level observations, not individual exception events — get_error_count.exception_count is the same error-observation total reported by find_exceptions.metadata.observation_count (including groups beyond the top 50). Exception details come from recorded metadata (exception.type / exception.message / exception.stacktrace, top-level or under metadata.attributes); absent values are null. Results are not a point-in-time snapshot.
Project Links
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-mcpTo 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 -yVia skild:
npx skild install @avivsinai/langfuse -t claude -yManual install:
cp -r skills/langfuse ~/.claude/skills/ # Claude Code
cp -r skills/langfuse ~/.codex/skills/ # Codex CLIAfter installing the skill, try:
help me debug langfuse traces
find exceptions in the last day
why was this user's session slow?The MCP server provides the tools; the skill provides the agent-facing workflow. See skills/langfuse/SKILL.md, skills/langfuse/references/setup.md, and skills/langfuse/references/tool-reference.md.
Tools (48 total)
Category | Tools |
Traces |
|
Observations |
|
Routing |
|
Sessions |
|
Exceptions |
|
Prompts |
|
Datasets |
|
Annotation Queues |
|
Scores |
|
Metrics |
|
Schema |
|
On Observations API v2, traces are built from root observations. fetch_traces omits traces without a root observation, and fetch_trace cannot find traces with no observations.
Dataset-run reads use the experiments API when the installed Langfuse SDK exposes it (Python SDK 4.13.1+). The older routes remain a fallback for self-hosted servers that do not serve experiments. delete_dataset_run uses the legacy delete route while it works; after that route is removed, it deletes the run's traces only when you pass delete_traces=True. Trace deletion also removes observations and related scores. create_dataset_run_item still uses the legacy link API; when that API is gone, create experiment data through the SDK experiment runner or OTel ingestion.
Dataset Item Updates (Upsert)
Langfuse uses upsert for dataset items. To edit an existing item, call create_dataset_item with item_id. If the ID exists, it updates; otherwise it creates a new item.
create_dataset_item(dataset_name="qa-test-cases", item_id="item_123", input={"question": "What is 2+2?"}, expected_output={"answer": "4"})Metrics Queries
query_metrics aggregates telemetry server-side (cost, latency, tokens, counts, score values) so agents can answer "what did inference cost?" or "what's p95 latency by model?" without pulling raw traces. Call get_metrics_schema for the full view/dimension/measure catalog.
query_metrics(
view="observations",
metrics=[{"measure": "totalCost", "aggregation": "sum"}, {"measure": "latency", "aggregation": "p95"}],
dimensions=["providedModelName"],
age=1440, # last 24h; or pass from_timestamp / to_timestamp
)High-cardinality fields (id, traceId, userId, sessionId) must be used in filters, not dimensions. The v2 metrics endpoint is Langfuse Cloud-only; self-hosted instances may return 404.
Selective Tool Loading
Load only the tool groups you need to reduce token overhead:
langfuse-mcp --tools traces,promptsAvailable groups: traces, observations, routing, sessions, exceptions, prompts, datasets, annotation_queues, scores, metrics, schema
The routing group is router-neutral. It reads Langfuse span observations with
metadata.schema_version: "mcp.route_decision.v1" and filters on route-decision
fields stored in observation metadata, such as decision_id, router_name,
provider, and capability_id.
Read-Only Mode
Disable all write operations for safer read-only access:
langfuse-mcp --read-only
# Or via environment variable
LANGFUSE_MCP_READ_ONLY=true langfuse-mcpThis disables: create_text_prompt, create_chat_prompt, update_prompt_labels, create_dataset, create_dataset_item, delete_dataset_item, create_dataset_run_item, delete_dataset_run, create_annotation_queue, create_annotation_queue_item, update_annotation_queue_item, delete_annotation_queue_item, create_annotation_queue_assignment, delete_annotation_queue_assignment
Default Output Mode
Set the MCP-exposed default output_mode so clients that omit the parameter automatically use your preferred mode:
langfuse-mcp --default-output-mode full_json_file
# Or via environment variable
LANGFUSE_MCP_DEFAULT_OUTPUT_MODE=full_json_file langfuse-mcpSupported values: compact, full_json_string, full_json_file
This updates the default shown in MCP tool schemas. Clients can still override it per call by passing output_mode explicitly.
Other Clients
Cursor
Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json for global):
{
"mcpServers": {
"langfuse": {
"command": "uvx",
"args": ["langfuse-mcp"],
"env": {
"LANGFUSE_PUBLIC_KEY": "pk-...",
"LANGFUSE_SECRET_KEY": "sk-...",
"LANGFUSE_HOST": "https://cloud.langfuse.com",
"LANGFUSE_MCP_DEFAULT_OUTPUT_MODE": "full_json_file"
}
}
}
}Docker (single project)
docker run --rm -i \
-e LANGFUSE_PUBLIC_KEY=pk-... \
-e LANGFUSE_SECRET_KEY=sk-... \
-e LANGFUSE_HOST=https://cloud.langfuse.com \
ghcr.io/avivsinai/langfuse-mcp:latestMultiple projects with profiles (stdio)
For local clients (Claude Code, Codex, Cursor), keep the credentials of each Langfuse
project in a profiles file and register one MCP server per project. Each server
starts with --profile <name>.
The file is TOML at $XDG_CONFIG_HOME/langfuse-mcp/profiles.toml (or
~/.config/langfuse-mcp/profiles.toml when XDG_CONFIG_HOME is not set). Use
--profiles-file PATH or LANGFUSE_MCP_PROFILES_FILE to read a different file.
[profiles.prod]
host = "https://cloud.langfuse.com"
public_key = "pk-lf-..."
secret_key_env = "LANGFUSE_PROD_SECRET_KEY" # read the secret from this env var
[profiles.staging]
host = "https://langfuse.staging.example.com"
public_key = "pk-lf-..."
secret_key = "sk-lf-..." # or give the value directlyEach of public_key, secret_key and host takes a literal value, or a
<field>_env key that names the environment variable that holds the value.
host defaults to https://cloud.langfuse.com.
claude mcp add langfuse-prod -- uvx langfuse-mcp --profile prod
claude mcp add langfuse-staging -- uvx langfuse-mcp --profile staging{
"mcpServers": {
"langfuse-prod": {
"command": "uvx",
"args": ["langfuse-mcp", "--profile", "prod"]
},
"langfuse-staging": {
"command": "uvx",
"args": ["langfuse-mcp", "--profile", "staging"]
}
}
}Precedence is CLI flags (--public-key, --secret-key, --host) > environment
variables (LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_HOST) > the
selected profile > defaults. When an environment variable overrides a profile
value, the server logs a warning. An unknown profile name or a missing profiles
file stops the server with an error that names the file and the available
profiles. LANGFUSE_MCP_PROFILE selects a profile when --profile is not given.
HTTP transport — shared server for multiple projects
Run one persistent server instance and route each MCP client to its own Langfuse
project by passing credentials in the Authorization header.
# Start a shared server (binds to localhost by default)
docker run -d -p 127.0.0.1:8000:8000 \
-e LANGFUSE_HOST=https://cloud.langfuse.com \
ghcr.io/avivsinai/langfuse-mcp:latest \
--transport streamable-http --bind-host 0.0.0.0Security note:
--bind-host 0.0.0.0exposes the port on all interfaces. In production, place the server behind a TLS-terminating reverse proxy (nginx, Caddy, Cloudflare Tunnel) that enforces HTTPS. TheAuthorizationheader containing your keys is transmitted in plaintext over plain HTTP. If startup credentials are set, the proxy must enforce authentication; otherwise unauthenticated callers without anAuthorizationheader can use the default project. For shared public HTTP deployments, omit defaultLANGFUSE_PUBLIC_KEY/LANGFUSE_SECRET_KEYcredentials unless the fronting proxy authenticates every request.
Register each project separately in your MCP client, passing its credentials as a
Basic auth header (base64(public_key:secret_key)):
# Generate the header value for each project:
echo -n "pk-lf-YOURKEY:sk-lf-YOURSECRET" | base64
# cGstbGYtWU9VUktFWTpzay1sZi1ZT1VSU0VDUkVU
# Register in Claude Code (one entry per project):
claude mcp add langfuse-audit \
--transport http http://localhost:8000/mcp \
-H "Authorization: Basic cGstbGYtWU9VUktFWTpzay1sZi1ZT1VSU0VDUkVU"
claude mcp add langfuse-staging \
--transport http http://localhost:8000/mcp \
-H "Authorization: Basic <base64 for staging project>"Auth semantics: Basic here carries Langfuse API keys, not user passwords. An
absent header falls back to startup env credentials (LANGFUSE_PUBLIC_KEY /
LANGFUSE_SECRET_KEY). Any malformed header is rejected outright — there is no
silent fallback to a different project.
Optional environment variables
Variable | Default | Description |
|
| Caps the lookback window for time-based tools ( |
| unset | Profile to load from the profiles file; same as |
|
| Path of the profiles file; same as |
|
| Per-request read timeout (seconds) for single-trace fetches ( |
Development
uv venv --python 3.14 .venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytestLicense
MIT
Available Tools
48 toolscreate_annotation_queueC
Create an annotation queue.
Inputs: name (required), description, score_config_ids. Returns: object
create_annotation_queue_assignmentB
Assign a user to an annotation queue.
Inputs: user_id (required), queue_id (required). Returns: object
create_annotation_queue_itemD
Create an annotation queue item.
Inputs: queue_id (required), object_id (required), object_type (required), status. Returns: object
create_chat_promptA
Create a new chat prompt version in Langfuse.
Chat prompts are arrays of role/content messages. Prompts are immutable; create a new version to update content. Labels are unique across versions.
Inputs: name (required), prompt (required), tags, config, +2 more. Returns: object
create_datasetA
Create a new dataset in the project.
Datasets are used to store evaluation test cases with input/expected output pairs.
Args:
ctx: Context object containing lifespan context with Langfuse client
name: Name for the new dataset (must be unique)
description: Optional description
metadata: Optional custom metadata
Returns:
A dictionary containing the created dataset details:
- id: Unique dataset identifier
- name: Dataset name
- description: Dataset description
- metadata: Custom metadata
- createdAt: Creation timestamp
Inputs: name (required), metadata, description. Returns: object
create_dataset_itemA
Create a new item in a dataset, or update if item_id already exists.
Dataset items store input/expected output pairs for evaluation. If item_id is provided
and already exists, the item will be updated (upsert behavior).
Args:
ctx: Context object containing lifespan context with Langfuse client
dataset_name: Name of the target dataset
input: Input data for the item
expected_output: Expected output for evaluation
metadata: Optional custom metadata
source_trace_id: Optional linked trace ID
source_observation_id: Optional linked observation ID
item_id: Optional custom ID (enables upsert)
status: Item status (ACTIVE or ARCHIVED)
Returns:
A dictionary containing the created/updated item details
Inputs: dataset_name (required), input, status, item_id, +4 more. Returns: object
create_dataset_run_itemA
Create a dataset run item and flush the ingestion write.
If this legacy API is gone, use the SDK experiment runner or OTel ingestion; neither can link an existing trace through this API.
Inputs: run_name (required), dataset_item_id (required), metadata, trace_id, +2 more. Returns: object
create_text_promptA
Create a new text prompt version in Langfuse.
Prompts are immutable; creating a new version is the only way to update prompt content. Labels are unique across versions - assigning a label here will move it from other versions.
Inputs: name (required), prompt (required), tags, config, +2 more. Returns: object
delete_annotation_queue_assignmentB
Unassign a user from an annotation queue.
Inputs: user_id (required), queue_id (required). Returns: object
delete_annotation_queue_itemC
Delete an annotation queue item.
Inputs: item_id (required), queue_id (required). Returns: object
delete_dataset_itemB
Delete a dataset item by ID.
This is a permanent deletion and cannot be undone.
Args:
ctx: Context object containing lifespan context with Langfuse client
item_id: The ID of the dataset item to delete
Returns:
A dictionary confirming the deletion
Inputs: item_id (required). Returns: object
delete_dataset_runA
Delete a run through the legacy route, or explicitly delete its traces after removal.
Trace deletion also removes observations and related scores. Set delete_traces=True to allow this broader replacement.
Inputs: run_name (required), dataset_name (required), delete_traces. Returns: object
fetch_observationA
Get a single observation by ID.
Args:
ctx: Context object containing lifespan context with Langfuse client
observation_id: The ID of the observation to fetch (unique identifier string)
output_mode: Controls the output format and detail level
Returns:
Based on output_mode:
- compact: Summarized observation object
- full_json_string: String containing the full JSON response
- full_json_file: Summarized observation object with file save info
Inputs: observation_id (required), output_mode. Returns: result
fetch_observationsB
Get observations filtered by type and other criteria.
Args:
ctx: Context object containing lifespan context with Langfuse client
type: The observation type to filter by (SPAN, GENERATION, EVENT, AGENT, TOOL, CHAIN, RETRIEVER, EVALUATOR, EMBEDDING or GUARDRAIL)
age: Minutes ago to start looking (e.g., 1440 for 24 hours)
name: Optional name filter (string pattern to match)
user_id: Optional user ID filter (exact match)
trace_id: Optional trace ID filter (exact match)
parent_observation_id: Optional parent observation ID filter (exact match)
page: Page number for pagination (starts at 1)
limit: Maximum number of observations to return per page
output_mode: Controls the output format and detail level
Returns:
Based on output_mode:
- compact: List of summarized observation objects
- full_json_string: String containing the full JSON response
- full_json_file: List of summarized observation objects with file save info
Inputs: age (required), name, page, type, +5 more. Returns: result
fetch_sessionsA
Get a list of sessions in the current project.
Args:
ctx: Context object containing lifespan context with Langfuse client
age: Minutes ago to start looking (e.g., 1440 for 24 hours)
page: Page number for pagination (starts at 1)
limit: Maximum number of sessions to return per page
output_mode: Controls the output format and detail level
Returns:
Based on output_mode:
- compact: List of summarized session objects
- full_json_string: String containing the full JSON response
- full_json_file: List of summarized session objects with file save info
Inputs: age (required), page, limit, output_mode. Returns: result
fetch_traceA
Get a single trace by ID with full details.
On Observations API v2, a trace is built from its root observation; a trace with no observations is not found.
Args:
ctx: Context object containing lifespan context with Langfuse client
trace_id: The ID of the trace to fetch (unique identifier string)
include_observations: If True, fetch and include the full observation objects. If False, the
observations field group is dropped entirely to avoid expensive per-observation IO.
Use True when you need access to system prompts, model parameters, or other details stored
within observations. Significantly increases response time but provides complete data.
output_mode: Controls the output format and detail level
Returns:
One of the following based on output_mode:
- For 'compact' and 'full_json_file': A response dictionary with the structure:
{
"data": Single trace object,
"metadata": {
"file_path": Path to saved file (only for full_json_file mode),
"file_info": File save details (only for full_json_file mode)
}
}
- For 'full_json_string': A string containing the full JSON response
Usage Tips:
- For quick browsing: use include_observations=False with output_mode="compact"
- For full data but viewable in responses: use include_observations=True with output_mode="compact"
- For complete data dumps: use include_observations=True with output_mode="full_json_file"
Inputs: trace_id (required), output_mode, include_observations. Returns: result
fetch_tracesB
Find traces based on filters. All filter parameters are optional.
On Observations API v2, each trace is built from its root observation; traces without a root observation do not appear.
Inputs: age (required), name, page, tags, +6 more. Returns: result
find_exceptionsA
Get error-level observations grouped by file path, function, type, name, or observation type.
Args:
ctx: Context object containing lifespan context with Langfuse client
age: Number of minutes to look back; capped by the configured maximum
group_by: How to group errors - "file" groups by recorded code.filepath, "function" by code.function,
"type" by recorded exception.type, "name" by observation name, or "observation_type" by
observation type
Returns:
List of error-observation counts grouped by the specified category. A group entry carries a
representative observation_id and trace_id. Counts describe error-level observations, NOT
individual exception events (which the standard observation listing does not expose).
Inputs: age (required), group_by. Returns: object
find_exceptions_in_fileB
Get detailed error info for a specific file (recorded code.filepath match).
Args:
ctx: Context object containing lifespan context with Langfuse client
filepath: Path to the file as recorded in Langfuse metadata (code.filepath)
age: Number of minutes to look back; capped by the configured maximum
output_mode: Controls the output format and detail level
Returns:
Based on output_mode:
- compact: List of summarized error records (top 10 newest after the full scan)
- full_json_string: String containing the full JSON response
- full_json_file: List of summarized error records with file save info
Inputs: age (required), filepath (required), output_mode. Returns: result
find_low_confidence_route_decisionsB
Find route decisions that are low-confidence or explicitly uncallable.
Inputs: age, page, limit, provider, +7 more. Returns: result
find_route_decisionsA
Find generic agent route decisions emitted as Langfuse SPAN observations.
This tool is router-neutral. It only treats observations with
metadata.schema_version == "mcp.route_decision.v1" as route decisions, and
it filters on fields inside observation metadata rather than display output.
Inputs: age, page, limit, provider, +6 more. Returns: result
get_annotation_queueB
Get a single annotation queue by ID.
Inputs: queue_id (required). Returns: object
get_annotation_queue_itemA
Get a specific annotation queue item by queue and item ID.
Inputs: item_id (required), queue_id (required). Returns: object
get_data_schemaA
Get schema of trace, span and event objects.
Args:
ctx: Context object containing lifespan context with Langfuse client
dummy: Unused parameter for API compatibility (can be left empty)
Returns:
String containing the detailed schema definitions for traces, spans, events,
and other core Langfuse data structures
Inputs: dummy. Returns: result
get_datasetA
Get a specific dataset by name.
Retrieves dataset details including metadata and item count.
Args:
ctx: Context object containing lifespan context with Langfuse client
name: The name of the dataset to fetch
Returns:
A dictionary containing dataset details:
- id: Unique dataset identifier
- name: Dataset name
- description: Dataset description
- metadata: Custom metadata
- items: List of dataset items (if included by the API)
- runs: List of dataset runs (if included by the API)
Inputs: name (required). Returns: object
get_dataset_itemA
Get a specific dataset item by ID.
Retrieves the full dataset item including input, expected output, metadata, and linked traces.
Args:
ctx: Context object containing lifespan context with Langfuse client
item_id: The ID of the dataset item to fetch
output_mode: How to format the response data
Returns:
A dictionary containing the dataset item details:
- id: Unique item identifier
- datasetId: Parent dataset ID
- input: Input data for the item
- expectedOutput: Expected output data
- metadata: Custom metadata
- sourceTraceId: Linked trace ID (if any)
- sourceObservationId: Linked observation ID (if any)
- status: Item status (ACTIVE or ARCHIVED)
Inputs: item_id (required), output_mode. Returns: result
get_dataset_runC
Get a dataset run, including any run items returned by the SDK.
Inputs: run_name (required), dataset_name (required), output_mode. Returns: result
get_error_countB
Get number of traces with error-level observations in last N minutes.
Args:
ctx: Context object containing lifespan context with Langfuse client
age: Number of minutes to look back; capped by the configured maximum
Returns:
Dictionary with error statistics: trace_count (distinct traces), observation_count
(error-level observations), and exception_count (the same error-observation total
as find_exceptions, not a count of individual exception events; see metadata.note).
Inputs: age (required). Returns: object
get_exception_detailsB
Get detailed error info for a trace/observation.
Args:
ctx: Context object containing lifespan context with Langfuse client
trace_id: The ID of the trace to analyze for errors (unique identifier string)
span_id: Optional observation ID to filter by (applies across all observation types)
output_mode: Controls the output format and detail level
Returns:
Based on output_mode:
- compact: List of summarized error records
- full_json_string: String containing the full JSON response
- full_json_file: List of summarized error records with file save info
Inputs: trace_id (required), span_id, output_mode. Returns: result
get_metrics_schemaA
Get the query schema for the metrics API (views, dimensions, measures, aggregations).
Companion to query_metrics: describes which views exist, the dimensions and measures
available on each, the supported aggregations/operators, and the query-object shape.
``dummy`` is unused and exists only for MCP API compatibility.
Inputs: dummy. Returns: result
get_promptA
Fetch a specific prompt by name with resolved dependencies.
Retrieves a prompt from Langfuse with all dependency tags resolved. Uses the SDK's
built-in caching for optimal performance.
Args:
ctx: Context object containing lifespan context with Langfuse client
name: The name of the prompt to fetch
label: Optional label to fetch (e.g., 'production'). Cannot be used with version.
version: Optional specific version number. Cannot be used with label.
Returns:
A dictionary containing the prompt details:
- id: Unique prompt identifier
- name: Prompt name
- version: Version number
- type: 'text' or 'chat'
- prompt: The prompt content (string for text, list for chat)
- labels: List of labels assigned to this version
- tags: List of tags
- config: Model configuration (temperature, model, etc.)
Raises:
ValueError: If both label and version are specified
LookupError: If prompt not found
Inputs: name (required), label, version. Returns: object
get_prompt_unresolvedA
Fetch a specific prompt by name WITHOUT resolving dependencies.
Returns raw prompt content with dependency tags intact (e.g., @@@langfusePrompt:name=xxx@@@) when
the SDK supports resolve=false. Otherwise returns the resolved prompt and marks metadata.resolved=True.
Useful for analyzing prompt composition and debugging dependency chains.
Args:
ctx: Context object containing lifespan context with Langfuse client
name: The name of the prompt to fetch
label: Optional label to fetch. Cannot be used with version.
version: Optional specific version number. Cannot be used with label.
Returns:
A dictionary containing the raw prompt details with dependency tags preserved.
Raises:
ValueError: If both label and version are specified
LookupError: If prompt not found
Inputs: name (required), label, version. Returns: object
get_route_decisionB
Fetch one route decision by metadata decision_id.
Inputs: decision_id (required), age, output_mode. Returns: result
get_score_v2A
Get a score by ID from Scores API v3 (the v2 route where v3 is not served).
Inputs: score_id (required). Returns: object
get_session_detailsA
Get detailed information about a specific session.
Args:
ctx: Context object containing lifespan context with Langfuse client
session_id: The ID of the session to retrieve (unique identifier string)
include_observations: If True, fetch and include the full observation objects instead of just IDs.
Use this when you need access to system prompts, model parameters, or other details stored
within observations. Significantly increases response time but provides complete data.
output_mode: Controls the output format and detail level
Returns:
Based on output_mode:
- compact: Summarized session details object
- full_json_string: String containing the full JSON response
- full_json_file: Summarized session details object with file save info
Usage Tips:
- For quick browsing: use include_observations=False with output_mode="compact"
- For full data but viewable in responses: use include_observations=True with output_mode="compact"
- For complete data dumps: use include_observations=True with output_mode="full_json_file"
Inputs: session_id (required), output_mode, include_observations. Returns: result
get_user_sessionsA
Get sessions for a user within a time range.
Args:
ctx: Context object containing lifespan context with Langfuse client
user_id: The ID of the user to retrieve sessions for (unique identifier string)
age: Minutes ago to start looking (e.g., 1440 for 24 hours)
include_observations: If True, fetch and include the full observation objects instead of just IDs.
Use this when you need access to system prompts, model parameters, or other details stored
within observations. Significantly increases response time but provides complete data.
output_mode: Controls the output format and detail level
Returns:
Based on output_mode:
- compact: List of summarized session objects
- full_json_string: String containing the full JSON response
- full_json_file: List of summarized session objects with file save info
Usage Tips:
- For quick browsing: use include_observations=False with output_mode="compact"
- For full data but viewable in responses: use include_observations=True with output_mode="compact"
- For complete data dumps: use include_observations=True with output_mode="full_json_file"
Inputs: age (required), user_id (required), output_mode, include_observations. Returns: result
list_annotation_queue_itemsB
List items in an annotation queue.
Inputs: queue_id (required), page, limit. Returns: object
list_annotation_queuesC
List annotation queues with pagination.
Inputs: page, limit. Returns: object
list_dataset_itemsA
List items in a dataset with pagination and optional filtering.
Returns dataset items with their input, expected output, and metadata.
Args:
ctx: Context object containing lifespan context with Langfuse client
dataset_name: The name of the dataset to list items from
source_trace_id: Optional filter by source trace ID
source_observation_id: Optional filter by source observation ID
page: Page number for pagination (starts at 1)
limit: Maximum items per page (max 100)
output_mode: How to format the response data
Returns:
A dictionary containing:
- data: List of dataset item objects
- metadata: Pagination info (page, limit, total, dataset_name)
Inputs: dataset_name (required), page, limit, output_mode, +2 more. Returns: result
list_dataset_run_itemsC
List dataset run items by dataset ID and run name.
Inputs: run_name (required), dataset_id (required), page, limit, +1 more. Returns: result
list_dataset_runsB
List runs for a dataset by dataset name.
Inputs: dataset_name (required), page, limit. Returns: object
list_datasetsA
List all datasets in the project with pagination.
Returns metadata about datasets including name, description, item count, and timestamps.
Args:
ctx: Context object containing lifespan context with Langfuse client
page: Page number for pagination (starts at 1)
limit: Maximum items per page (max 100)
Returns:
A dictionary containing:
- data: List of dataset metadata objects
- metadata: Pagination info (page, limit, total)
Inputs: page, limit. Returns: object
list_promptsB
List and filter prompts in the project.
Returns metadata about prompts including versions, labels, tags, and last updated time.
Args:
ctx: Context object containing lifespan context with Langfuse client
name: Optional filter by exact prompt name
label: Optional filter by label on any version
tag: Optional filter by tag
page: Page number for pagination (starts at 1)
limit: Maximum items per page (max 100)
Returns:
A dictionary containing:
- data: List of prompt metadata objects
- metadata: Pagination info (page, limit, total)
Inputs: tag, name, page, label, +1 more. Returns: object
list_scores_v2A
List scores via Scores API v3 with optional filters (GET /v2/scores where v3 is not served).
With operator ``=`` and a value, v3 defaults an omitted data_type to NUMERIC; pass BOOLEAN for boolean scores.
Strict ``>``/``<`` can return fewer than limit rows on a page after boundary rows are dropped; next_page shows whether more rows exist.
Inputs: name, page, limit, value, +13 more. Returns: object
query_metricsA
Query aggregated metrics (cost, latency, token usage, counts, score values) from Langfuse.
Wraps the Langfuse v2 metrics endpoint. Use this for analytics questions — "what did
inference cost in the last 24h grouped by model", "p95 latency per prompt", "score
distribution by name" — instead of pulling raw observations and aggregating client-side.
Per-parameter contracts live in the Field descriptions above.
Notes:
- The v2 metrics endpoint is Langfuse Cloud-only; self-hosted instances may return 404.
- Recently-ingested data can lag (OTEL ingestion delay up to ~10 minutes).
- High-cardinality fields (id, traceId, userId, sessionId) must be filters, not dimensions.
Inputs: view (required), metrics (required), age, filters, +6 more. Returns: result
summarize_route_decisionsC
Summarize generic route decisions for a trace, session, router, provider, or capability.
Inputs: age, page, limit, provider, +5 more. Returns: object
update_annotation_queue_itemB
Update the status of an annotation queue item.
Inputs: status (required), item_id (required), queue_id (required). Returns: object
update_prompt_labelsA
Update labels for a specific prompt version.
This is the only supported mutation for existing prompts. Provided labels are added to the version (existing labels are preserved). Labels are unique across versions, and the 'latest' label is managed by Langfuse.
Inputs: name (required), labels (required), version (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 48 tools
Most tools map to a distinct resource+action, but the error/exception cluster (get_error_count, find_exceptions, find_exceptions_in_file, get_exception_details) and route-decision tools have overlapping analytical purposes. An agent can distinguish them only by carefully reading descriptions, and with 48 tools the misselection risk is elevated.
All tools use snake_case, but verb conventions are mixed across list/get/fetch/query/find/summarize/create/update/delete, and _v2 suffixes appear in list_scores_v2 and get_score_v2. The pattern is readable but not consistently predictable.
48 tools is well above the typical 3–15 range. Although Langfuse is a broad platform, the inclusion of many niche CRUD and route-decision tools makes the surface heavy and increases selection burden.
Core read/query workflows for traces, observations, sessions, metrics, prompts, and datasets are covered. However, management coverage has notable gaps: datasets lack update/delete, annotation queues lack update/delete, and scores have no create/delete surface.
Maintenance
Related MCP Connectors
Cloud hosted Okahu MCP server that helps you manage genAI trace data
Hosted MCP server for LLM cost estimation, model comparison, and budget-aware routing.
MCP server for Statsig API - interact with Statsig's feature flags, experiments, and analytics
MCP observability. Query live traffic, errors, duration, and alerts from your AI agent.
Related MCP Servers
- AlicenseBqualityDmaintenanceModel Context Protocol server for Langfuse observability. Query traces, analyze accuracy, detect failures, track costs, debug latency, manage prompts and datasets.582MIT
- AlicenseAqualityCmaintenanceComprehensive MCP server for Langfuse, enabling AI assistants to access and manage traces, observations, scores, datasets, and sessions for observability.2418 npm2MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server for comprehensive monitoring and observability of systems using Langfuse.1MIT
- AlicenseNot gradedqualityFmaintenanceMCP server for Langfuse providing 50 tools for prompt management, observability, instance/organization management, and metrics tracking via natural language.16 npmMIT