Langfuse MCP

Create an annotation queue.

Assign a user to an annotation queue.

Create an annotation queue item.

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.

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

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

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.

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.

Unassign a user from an annotation queue.

Delete an annotation queue item.

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

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.

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

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

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

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"

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.

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).

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

Find route decisions that are low-confidence or explicitly uncallable.

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.

Get a single annotation queue by ID.

Get a specific annotation queue item by queue and item ID.

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

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)

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)

Get a dataset run, including any run items returned by the SDK.

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 (always null — individual exception events are not retrievable from the standard observation listing; see metadata.note).

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

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.

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

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

Fetch one route decision by metadata decision_id.

Get a score by ID from Scores API v3 (the v2 route where v3 is not served).

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"

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"

List items in an annotation queue.

List annotation queues with pagination.

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)

List dataset run items by dataset ID and run name.

List runs for a dataset by dataset name.

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)

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)

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.

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.

Summarize generic route decisions for a trace, session, router, provider, or capability.

Update the status of an annotation queue item.

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.