Каталог MCP
avivsinai/langfuse-mcp

avivsinai/langfuse-mcp

Langfuse MCP Server - агентский интерфейс для Langfuse observability. Позволяет агентам запрашивать трейсы, отлаживать исключения, управлять промптами и датасетами, используя трассировку Langfuse д...

README

48 инструментов

Версии

Установить сервер

Langfuse MCP Server

Agent-facing Model Context Protocol server and skill for Langfuse observability.

Use langfuse-mcp from Claude Code, Codex, Cursor, or any MCP client to query traces, inspect generations, debug exceptions, analyze sessions, manage prompts, browse datasets, and understand what your AI agents did in production.

What You Can Do

Debug failing agent runs from Langfuse traces and observations.
Find exceptions, slow generations, high-latency spans, and affected users.
Inspect sessions and user journeys without leaving your agent workflow.
Manage prompt versions, labels, datasets, annotation queues, and scores.
Install the included langfuse agent skill for ready-made debugging playbooks.

Project Links

Quick Start
Agent Skill
Tools
Selective Tool Loading
Read-Only Mode
Other Clients

Why langfuse-mcp?

Langfuse is where your traces live. langfuse-mcp makes that telemetry directly usable by agents that need to answer questions like "what failed?", "why was this slow?", "which prompt version ran?", or "what happened in this user's session?"

Инструменты были проиндексированы: 11.09.2026

create_annotation_queue

Создаёт очередь аннотаций.

Параметры

descriptionstring | null
Optional queue description
namestringобязательный
Unique queue name
score_config_idsstring[] | null
Optional score config IDs attached to this queue

create_annotation_queue_assignment

Назначить пользователя в очередь аннотации.

Параметры

queue_idstringобязательный
Annotation queue ID
user_idstringобязательный
User ID to assign

create_annotation_queue_item

Создать элемент очереди аннотаций.

Параметры

object_idstringобязательный
Object ID to enqueue
object_typestringобязательный
Object type, for example TRACE or OBSERVATION
queue_idstringобязательный
Annotation queue ID
statusstring | null
Optional status

create_chat_prompt

Создайте новую версию чат-промпта в Langfuse. Чат-промпты — это массивы сообщений с ролью/содержанием. Промпты неизменяемы; создайте новую версию, чтобы обновить содержимое. Метки уникальны для всех версий.

Параметры

commit_messagestring | null
Optional commit message describing the changes
configobject | null
Optional JSON config (e.g., {model: 'gpt-4', temperature: 0.7})
labelsstring[] | null
Labels to assign (e.g., ['production', 'staging'])
namestringобязательный
The name of the prompt to create
promptobject[]обязательный
Chat messages in the format [{role: 'system'|'user'|'assistant', content: '...'}]
tagsstring[] | null
Optional tags for organization (e.g., ['experimental', 'v2'])

create_dataset

Создаёт новый набор данных в проекте. Наборы данных хранят тестовые сценарии оценки с парами «вход/ожидаемый выход». Параметры: ctx: Контекстный объект, содержащий контекст времени жизни вместе с клиентом Langfuse name: Имя нового набора данных (должно быть уникальным) description: Необязательное описание metadata: Необязательные пользовательские метаданные Возвращает: Словарь с подробностями созданного набора данных: - id: Уникальный идентификатор набора данных - name: Имя набора данных - description: Описание набора данных - metadata: Пользовательские метаданные - createdAt: Временная метка создания

Параметры

descriptionstring | null
Optional description of the dataset
metadataobject | null
Optional custom metadata as key-value pairs
namestringобязательный
Name for the new dataset (must be unique in project)

create_dataset_item

Создаёт новый элемент в наборе данных или обновляет существующий, если item_id уже есть. Элементы набора данных хранят пары «входные данные / ожидаемый результат» для оценки. Если item_id указан и уже существует, элемент будет обновлён (поведение upsert). Параметры: ctx: Контекстный объект с контекстом времени жизни, содержащим клиент Langfuse dataset_name: Имя целевого набора данных input: Входные данные для элемента expected_output: Ожидаемый результат для оценки metadata: Необязательные пользовательские метаданные source_trace_id: Необязательный идентификатор связанного трейса source_observation_id: Необязательный идентификатор связанного наблюдения item_id: Необязательный пользовательский идентификатор (включает upsert) status: Статус элемента (ACTIVE или ARCHIVED) Возвращает: Словарь с деталями созданного/обновлённого элемента

Параметры

dataset_namestringобязательный
Name of the dataset to add the item to
expected_outputany
Expected output data for evaluation (any JSON-serializable value)
inputany
Input data for the dataset item (any JSON-serializable value)
item_idstring | null
Optional custom ID for the item (for upsert behavior)
metadataobject | null
Optional custom metadata as key-value pairs
source_observation_idstring | null
Optional observation ID to link this item to
source_trace_idstring | null
Optional trace ID to link this item to
statusenum | null
Item status (default: ACTIVE)

create_dataset_run_item

Создать элемент запуска набора данных и сбросить запись приема данных.

Параметры

dataset_item_idstringобязательный
Dataset item ID to include in the run
metadataobject | null
Optional run-item metadata
observation_idstring | null
Optional observation ID linked to this run item
run_descriptionstring | null
Optional run description
run_namestringобязательный
Dataset run name to append this item to
trace_idstring | null
Optional trace ID linked to this run item

create_text_prompt

Создаёт новую версию текстового промпта в Langfuse. Промпты неизменяемы; единственный способ обновить содержимое промпта — создать новую версию. Метки уникальны между версиями: присвоение метки здесь переместит её с других версий.

Параметры

commit_messagestring | null
Optional commit message describing the changes
configobject | null
Optional JSON config (e.g., {model: 'gpt-4', temperature: 0.7})
labelsstring[] | null
Labels to assign (e.g., ['production', 'staging'])
namestringобязательный
The name of the prompt to create
promptstringобязательный
Prompt text content (supports {{variables}})
tagsstring[] | null
Optional tags for organization (e.g., ['experimental', 'v2'])

delete_annotation_queue_assignment

Открепить пользователя от очереди аннотаций.

Параметры

queue_idstringобязательный
Annotation queue ID
user_idstringобязательный
User ID to unassign

delete_annotation_queue_item

Удалить элемент очереди аннотаций.

Параметры

item_idstringобязательный
Annotation queue item ID
queue_idstringобязательный
Annotation queue ID

delete_dataset_item

Удаляет элемент датасета по ID. Это полное удаление, его нельзя отменить. Аргументы: ctx: Контекстный объект, содержащий контекст времени жизни с клиентом Langfuse item_id: ID элемента датасета для удаления Возвращает: Словарь, подтверждающий удаление

Параметры

item_idstringобязательный
The ID of the dataset item to delete

delete_dataset_run

Удалить запуск набора данных по имени набора данных и имени запуска.

Параметры

dataset_namestringобязательный
The name of the dataset that owns the run
run_namestringобязательный
The dataset run name to delete

fetch_observation

Получить одну запись по ID. Аргументы: ctx: объект Context, содержащий контекст времени жизни с клиентом Langfuse observation_id: ID записи для получения (строка уникального идентификатора) output_mode: управляет форматом вывода и степенью детализации Возвращаемое значение: В зависимости от output_mode: - compact: сжатый объект записи - full_json_string: строка, содержащая полный JSON-ответ - full_json_file: сжатый объект записи с информацией о сохранении в файл

Параметры

observation_idstringобязательный
The ID of the observation to fetch (unique identifier string)
output_modeenum
Controls the output format and action. 'compact' (default): Returns a summarized JSON object optimized for direct agent consumption. 'full_json_string': Returns the complete, raw JSON data serialized as a string. 'full_json_file': Returns a summarized JSON object AND saves the complete data to a file.

fetch_observations

Возвращает наблюдения, отфильтрованные по типу и другим критериям. Аргументы: ctx: Контекстный объект, содержащий контекст жизненного цикла с клиентом Langfuse type: Тип наблюдения для фильтрации (SPAN, GENERATION или EVENT) age: Количество минут назад, с которого начинать поиск (например, 1440 для 24 часов) name: Необязательный фильтр по имени (шаблон строки для совпадения) user_id: Необязательный фильтр по ID пользователя (точное совпадение) trace_id: Необязательный фильтр по ID трейса (точное совпадение) parent_observation_id: Необязательный фильтр по ID родительского наблюдения (точное совпадение) page: Номер страницы для пагинации (начиная с 1) limit: Максимальное количество наблюдений на одной странице output_mode: Управляет форматом вывода и степенью детализации Возвращает: В зависимости от output_mode: - compact: Список сокращённых объектов наблюдений - full_json_string: Строка с полным ответом в формате JSON - full_json_file: Список сокращённых объектов наблюдений с информацией о сохранении в файл

Параметры

ageintegerобязательный
Minutes ago to start looking (e.g., 1440 for 24 hours)
limitinteger
Maximum number of observations to return per page
namestring | null
Optional name filter (string pattern to match)
output_modeenum
Controls the output format and action. 'compact' (default): Returns a summarized JSON object optimized for direct agent consumption. 'full_json_string': Returns the complete, raw JSON data serialized as a string. 'full_json_file': Returns a summarized JSON object AND saves the complete data to a file.
pageinteger
Page number for pagination (starts at 1)
parent_observation_idstring | null
Optional parent observation ID filter (exact match)
trace_idstring | null
Optional trace ID filter (exact match)
typeenum | null
The observation type to filter by ('SPAN', 'GENERATION', or 'EVENT')
user_idstring | null
Optional user ID filter (exact match)

fetch_sessions

Получить список сессий в текущем проекте. Аргументы: ctx: Объект Context, содержащий контекст времени жизни с клиентом Langfuse age: Сколько минут назад начинать поиск (например, 1440 (24 часа)) page: Номер страницы для пагинации (начинается с 1) limit: Максимальное количество сессий на страницу output_mode: Управляет форматом вывода и детализацией Возвращает: В зависимости от output_mode: - compact: Список кратких объектов сессий - full_json_string: Строка с полным JSON-ответом - full_json_file: Список кратких объектов сессий с информацией о сохранении в файл

Параметры

ageintegerобязательный
Minutes ago to start looking (e.g., 1440 for 24 hours)
limitinteger
Maximum number of sessions to return per page
output_modeenum
Controls the output format and action. 'compact' (default): Returns a summarized JSON object optimized for direct agent consumption. 'full_json_string': Returns the complete, raw JSON data serialized as a string. 'full_json_file': Returns a summarized JSON object AND saves the complete data to a file.
pageinteger
Page number for pagination (starts at 1)

fetch_trace

Получает один trace по ID со всеми деталями. Аргументы: ctx: Контекстный объект, содержащий контекст жизненного цикла с клиентом Langfuse trace_id: ID запрашиваемого trace (строка уникального идентификатора) include_observations: Если True — получает и включает полные объекты observation. Если False — группа полей observations полностью отбрасывается, чтобы избежать дорогих операций ввода-вывода для каждого observation. Используйте True, когда нужен доступ к системным промптам, параметрам модели или другим деталям, хранящимся внутри observations. Значительно увеличивает время ответа, но предоставляет полные данные. output_mode: Управляет форматом вывода и уровнем детализации Возвращает: Одно из следующего в зависимости от output_mode: - Для 'compact' и 'full_json_file': словарь ответа со структурой: { "data": Объект одного trace, "metadata": { "file_path": Путь к сохранённому файлу (только для full_json_file), "file_info": Детали сохранения файла (только для full_json_file) } } - Для 'full_json_string': строка, содержащая полный JSON-ответ Советы по использованию: - Для быстрого просмотра: используйте include_observations=False с output_mode="compact" - Для полных данных, но с возможностью просмотра в ответах: используйте include_observations=True с output_mode="compact" - Для полного дампа данных: используйте include_observations=True с output_mode="full_json_file"

Параметры

include_observationsboolean
If True, fetch and include the full observation objects. If False, the observations field group is dropped entirely to avoid the expensive per-observation IO that dominates large-trace payloads. 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. Pairs well with output_mode='full_json_file' for complete dumps.
output_modeenum
Controls the output format and action. 'compact' (default): Returns a summarized JSON object optimized for direct agent consumption. 'full_json_string': Returns the complete, raw JSON data serialized as a string. 'full_json_file': Returns a summarized JSON object AND saves the complete data to a file.
trace_idstringобязательный
The ID of the trace to fetch (unique identifier string)

fetch_traces

Найти следы по фильтрам. Все параметры фильтра необязательны.

Параметры

ageintegerобязательный
Minutes ago to start looking (e.g., 1440 for 24 hours)
include_observationsboolean
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.
limitinteger
Maximum number of traces to return per page
metadataobject | null
Metadata fields to filter by
namestring | null
Name of the trace to filter by
output_modeenum
Controls the output format: 'compact' (default) returns summarized JSON, 'full_json_string' returns complete raw JSON as string, 'full_json_file' saves complete data to file and returns summary with path.
pageinteger
Page number for pagination (starts at 1)
session_idstring | null
Session ID to filter traces by
tagsstring | null
Tag or comma-separated list of tags to filter traces by
user_idstring | null
User ID to filter traces by

find_exceptions

Получает количество исключений, сгруппированных по пути к файлу, функции или типу. Args: ctx: Контекстный объект, содержащий контекст времени жизни с клиентом Langfuse age: Количество минут для просмотра назад; ограничено максимальным настроенным значением group_by: Как группировать исключения - "file" группирует по имени файла, "function" группирует по имени функции, или "type" группирует по типу исключения Returns: Список количества исключений, сгруппированных по указанной категории (file, function или type)

Параметры

ageintegerобязательный
Number of minutes to look back (positive integer, max 7 days/10080 minutes)
group_byenum
How to group exceptions - 'file' groups by filename, 'function' groups by function name, or 'type' groups by exception type

find_exceptions_in_file

Получает подробную информацию об исключениях для конкретного файла. Аргументы: ctx: Объект контекста, содержащий контекст времени жизни с клиентом Langfuse filepath: Путь к файлу для поиска исключений (полный путь с расширением) age: Количество минут для поиска в прошлом; ограничено настроенным максимумом output_mode: Управляет форматом вывода и степенью детализации Возвращает: В зависимости от output_mode: - compact: Список сжатых подробностей об исключениях - full_json_string: Строка с полным JSON-ответом - full_json_file: Список сжатых подробностей об исключениях с информацией о сохранении в файл

Параметры

ageintegerобязательный
Number of minutes to look back (positive integer, max 7 days/10080 minutes)
filepathstringобязательный
Path to the file to search for exceptions (full path including extension)
output_modeenum
Controls the output format and action. 'compact' (default): Returns a summarized JSON object optimized for direct agent consumption. 'full_json_string': Returns the complete, raw JSON data serialized as a string. 'full_json_file': Returns a summarized JSON object AND saves the complete data to a file.

find_low_confidence_route_decisions

Найди решения маршрутов с низкой уверенностью или явно невызываемые.

Параметры

ageinteger
Number of minutes to look back (positive integer, max 7 days/10080 minutes)
capability_idstring | null
Optional route-decision metadata capability_id filter
include_uncallableboolean
Also return decisions with metadata callable=false
limitinteger
Maximum number of matching route decisions to return
max_confidencenumber
Return route decisions with confidence at or below this value
output_modeenum
Controls the output format and action. 'compact' (default): Returns a summarized JSON object optimized for direct agent consumption. 'full_json_string': Returns the complete, raw JSON data serialized as a string. 'full_json_file': Returns a summarized JSON object AND saves the complete data to a file.
pageinteger
Page number for pagination (starts at 1)
providerstring | null
Optional route-decision metadata provider filter
router_namestring | null
Optional route-decision metadata router_name filter
session_idstring | null
Optional route-decision metadata session_id filter
trace_idstring | null
Optional Langfuse trace ID filter

find_route_decisions

Находит решения о маршрутизации агентов общего назначения, эмитированные как наблюдения SPAN в Langfuse. Этот инструмент не зависит от маршрутизатора. Он считает решениями о маршрутизации только те наблюдения, у которых metadata.schema_version == "mcp.route_decision.v1", и фильтрует по полям внутри метаданных наблюдения, а не по отображаемым данным.

Параметры

ageinteger
Number of minutes to look back (positive integer, max 7 days/10080 minutes)
capability_idstring | null
Optional route-decision metadata capability_id filter
decision_idstring | null
Optional route-decision metadata decision_id filter
limitinteger
Maximum number of route decisions to return per page
output_modeenum
Controls the output format and action. 'compact' (default): Returns a summarized JSON object optimized for direct agent consumption. 'full_json_string': Returns the complete, raw JSON data serialized as a string. 'full_json_file': Returns a summarized JSON object AND saves the complete data to a file.
pageinteger
Page number for pagination (starts at 1)
providerstring | null
Optional route-decision metadata provider filter
router_namestring | null
Optional route-decision metadata router_name filter
session_idstring | null
Optional route-decision metadata session_id filter
trace_idstring | null
Optional Langfuse trace ID filter

get_annotation_queue

Получить одну очередь аннотаций по ID.

Параметры

queue_idstringобязательный
Annotation queue ID

get_annotation_queue_item

Получить конкретный элемент очереди аннотаций по ID очереди и ID элемента.

Параметры

item_idstringобязательный
Annotation queue item ID
queue_idstringобязательный
Annotation queue ID

get_data_schema

Получить схему объектов trace, span и event. Аргументы: ctx: Context-объект, содержащий контекст жизненного цикла с клиентом Langfuse dummy: Неиспользуемый параметр для совместимости API (можно оставить пустым) Возвращает: Строку с подробным описанием схемы для traces, spans, events и других базовых структур данных Langfuse

Параметры

dummystring

get_dataset

Получить конкретный набор данных по имени. Извлекает детали набора данных, включая метаданные и количество элементов. Аргументы: ctx: Объект контекста, содержащий контекст времени жизни с клиентом Langfuse name: Имя набора данных для получения Возвращает: Словарь с деталями набора данных: - id: Уникальный идентификатор набора данных - name: Имя набора данных - description: Описание набора данных - metadata: Пользовательские метаданные - items: Список элементов набора данных (если включены API) - runs: Список прогонов набора данных (если включены API)

Параметры

namestringобязательный
The name of the dataset to fetch

get_dataset_item

Получить конкретный элемент датасета по ID. Возвращает полную запись элемента датасета: входные данные, ожидаемый выход, метаданные и связанные трейсы. Аргументы: ctx: Контекстный объект, содержащий lifespan context с клиентом Langfuse item_id: ID элемента датасета для загрузки output_mode: Формат ответных данных Возвращает: Словарь с деталями элемента датасета: - id: Уникальный идентификатор элемента - datasetId: ID родительского датасета - input: Входные данные - expectedOutput: Ожидаемый выход - metadata: Пользовательские метаданные - sourceTraceId: ID связанного трейса (если есть) - sourceObservationId: ID связанного наблюдения (если есть) - status: Статус элемента (ACTIVE или ARCHIVED)

Параметры

item_idstringобязательный
The ID of the dataset item to fetch
output_modeenum
Output format: 'compact' truncates, 'full_json_string' returns full data, 'full_json_file' writes to file

get_dataset_run

Получить запуск набора данных, включая все элементы запуска, возвращённые SDK.

Параметры

dataset_namestringобязательный
The name of the dataset that owns the run
output_modeenum
Output format: 'compact' truncates, 'full_json_string' returns full data, 'full_json_file' writes to file
run_namestringобязательный
The dataset run name to fetch

get_error_count

Получает количество трейсов с исключениями за последние N минут. Аргументы: ctx: объект Context, содержащий контекст времени жизни с клиентом Langfuse age: количество минут для поиска; ограничено настроенным максимумом Возвращает: Словарь со статистикой ошибок, включая количество трейсов, наблюдений и исключений

Параметры

ageintegerобязательный
Number of minutes to look back (positive integer, max 7 days/10080 minutes)

get_exception_details

Получает подробную информацию об исключениях для trace/span. Аргументы: ctx: Объект контекста, содержащий контекст времени жизни с клиентом Langfuse trace_id: ID трейса для анализа исключений (строка уникального идентификатора) span_id: Опциональный ID спана для фильтрации по конкретному спану (строка уникального идентификатора) output_mode: Управляет форматом вывода и уровнем детализации Возвращает: В зависимости от output_mode: - compact: Список сжатых описаний исключений - full_json_string: Строка, содержащая полный JSON-ответ - full_json_file: Список сжатых описаний исключений с информацией о сохранении в файл

Параметры

output_modeenum
Controls the output format and action. 'compact' (default): Returns a summarized JSON object optimized for direct agent consumption. 'full_json_string': Returns the complete, raw JSON data serialized as a string. 'full_json_file': Returns a summarized JSON object AND saves the complete data to a file.
span_idstring | null
Optional span ID to filter by specific span (unique identifier string)
trace_idstringобязательный
The ID of the trace to analyze for exceptions (unique identifier string)

get_metrics_schema

Получить схему запросов для metrics API (представления, измерения, показатели, агрегации). Сопутствующий инструмент для query_metrics: описывает, какие представления существуют, какие измерения и показатели доступны для каждого, поддерживаемые агрегации/операторы и форму query-объекта. dummy не используется и существует только для совместимости с MCP API.

Параметры

dummystring

get_prompt

Получает конкретный промпт по имени с разрешёнными зависимостями. Извлекает промпт из Langfuse со всеми разрешёнными тегами зависимостей. Использует встроенное кэширование SDK для оптимальной производительности. Аргументы: ctx: объект Context, содержащий контекст времени жизни с клиентом Langfuse name: имя промпта для получения label: опциональная метка для получения (например, 'production'). Нельзя использовать вместе с version. version: опциональный номер версии. Нельзя использовать вместе с label. Возвращает: Словарь с деталями промпта: - id: уникальный идентификатор промпта - name: имя промпта - version: номер версии - type: 'text' или 'chat' - prompt: содержимое промпта (строка для text, список для chat) - labels: список меток, назначенных этой версии - tags: список тегов - config: конфигурация модели (temperature, model и т.д.) Вызывает исключения: ValueError: если указаны и label, и version LookupError: если промпт не найден

Параметры

labelstring | null
Label to fetch (e.g., 'production', 'staging'). Mutually exclusive with version.
namestringобязательный
The name of the prompt to fetch
versioninteger | null
Specific version number to fetch. Mutually exclusive with label.

get_prompt_unresolved

Получает конкретный prompt по имени БЕЗ разрешения зависимостей. Возвращает исходное содержимое prompt с нетронутыми тегами зависимостей (например, @@@langfusePrompt:name=xxx@@@), если SDK поддерживает resolve=false. В противном случае возвращает разрешённый prompt и помечает metadata.resolved=True. Полезен для анализа состава prompt и отладки цепочек зависимостей. Args: ctx: Объект Context, содержащий жизненный контекст с клиентом Langfuse name: Имя prompt'а для получения label: Необязательная метка для получения. Нельзя использовать вместе с version. version: Необязательный номер версии. Нельзя использовать вместе с label. Returns: Словарь, содержащий необработанные детали prompt с сохранёнными тегами зависимостей. Raises: ValueError: если указаны и label, и version LookupError: если prompt не найден

Параметры

labelstring | null
Label to fetch (e.g., 'production', 'staging'). Mutually exclusive with version.
namestringобязательный
The name of the prompt to fetch
versioninteger | null
Specific version number to fetch. Mutually exclusive with label.

get_route_decision

Получить одно решение маршрута по метаданным decision_id.

Параметры

ageinteger
Number of minutes to look back (positive integer, max 7 days/10080 minutes)
decision_idstringобязательный
Route-decision metadata decision_id to fetch
output_modeenum
Controls the output format and action. 'compact' (default): Returns a summarized JSON object optimized for direct agent consumption. 'full_json_string': Returns the complete, raw JSON data serialized as a string. 'full_json_file': Returns a summarized JSON object AND saves the complete data to a file.

get_score_v2

Получает оценку по ID из scores API (v3 score_v_2 или v4 scores).

Параметры

score_idstringобязательный
Score ID

get_session_details

Получить подробную информацию о конкретной сессии. Аргументы: ctx: объект Context, содержащий контекст времени жизни с клиентом Langfuse session_id: идентификатор сессии для получения (строка уникального идентификатора) include_observations: если True, получает и включает полные объекты наблюдений вместо простых идентификаторов. Используйте это, когда вам нужен доступ к системным промптам, параметрам модели или другим деталям, хранящимся в наблюдениях. Значительно увеличивает время ответа, но предоставляет полные данные. output_mode: управляет форматом вывода и уровнем детализации Возвращает: В зависимости от output_mode: - compact: объект с краткой информацией о сессии - full_json_string: строка, содержащая полный JSON ответ - full_json_file: объект с краткой информацией о сессии и информацией о сохранении файла Советы по использованию: - Для быстрого просмотра: используйте include_observations=False с output_mode="compact" - Для полных данных, но доступных в ответе: используйте include_observations=True с output_mode="compact" - Для полного дампа данных: используйте include_observations=True с output_mode="full_json_file"

Параметры

include_observationsboolean
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. Pairs well with output_mode='full_json_file' for complete dumps.
output_modeenum
Controls the output format and action. 'compact' (default): Returns a summarized JSON object optimized for direct agent consumption. 'full_json_string': Returns the complete, raw JSON data serialized as a string. 'full_json_file': Returns a summarized JSON object AND saves the complete data to a file.
session_idstringобязательный
The ID of the session to retrieve (unique identifier string)

get_user_sessions

Получает сессии пользователя за заданный временной промежуток. Аргументы: ctx: объект контекста, содержащий контекст времени жизни с клиентом Langfuse user_id: идентификатор пользователя, для которого нужно получить сессии (уникальная строка) age: сколько минут назад начинать поиск (например, 1440 для 24 часов) include_observations: если True, получать и включать полные объекты наблюдений вместо только ID. Используйте, когда нужен доступ к системным промптам, параметрам модели или другим деталям, хранящимся в наблюдениях. Значительно увеличивает время ответа, но даёт полные данные. output_mode: управляет форматом и детализацией вывода Возвращает: В зависимости от output_mode: - compact: список сводных объектов сессий - full_json_string: строка с полным JSON-ответом - full_json_file: список сводных объектов сессий с информацией о сохранении в файл Советы по использованию: - Для быстрого просмотра: используйте include_observations=False с output_mode="compact" - Для полных данных, но доступных для просмотра в ответах: используйте include_observations=True с output_mode="compact" - Для выгрузки полных данных: используйте include_observations=True с output_mode="full_json_file"

Параметры

ageintegerобязательный
Minutes ago to start looking (e.g., 1440 for 24 hours)
include_observationsboolean
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. Pairs well with output_mode='full_json_file' for complete dumps.
output_modeenum
Controls the output format and action. 'compact' (default): Returns a summarized JSON object optimized for direct agent consumption. 'full_json_string': Returns the complete, raw JSON data serialized as a string. 'full_json_file': Returns a summarized JSON object AND saves the complete data to a file.
user_idstringобязательный
The ID of the user to retrieve sessions for

list_annotation_queue_items

Вывести список элементов в очереди аннотаций.

Параметры

limitinteger
Items per page (max 100)
pageinteger
Page number for pagination (starts at 1)
queue_idstringобязательный
Annotation queue ID

list_annotation_queues

Список очередей аннотации с пагинацией.

Параметры

limitinteger
Items per page (max 100)
pageinteger
Page number for pagination (starts at 1)

list_dataset_items

Выводит список элементов датасета с постраничной разбивкой и опциональной фильтрацией. Возвращает элементы датасета: входные данные, ожидаемый результат и метаданные. Аргументы: ctx: объект Context, содержащий контекст времени жизни с клиентом Langfuse dataset_name: имя датасета, из которого нужно вывести элементы source_trace_id: опциональный фильтр по идентификатору исходного трейса source_observation_id: опциональный фильтр по идентификатору исходного наблюдения page: номер страницы для постраничной навигации (начиная с 1) limit: максимальное количество элементов на странице (не более 100) output_mode: способ форматирования ответных данных Возвращает: Словарь, содержащий: - data: список объектов элементов датасета - metadata: информация о постраничной навигации (page, limit, total, dataset_name)

Параметры

dataset_namestringобязательный
The name of the dataset to list items from
limitinteger
Items per page (max 100)
output_modeenum
Output format: 'compact' truncates, 'full_json_string' returns full data, 'full_json_file' writes to file
pageinteger
Page number for pagination (starts at 1)
source_observation_idstring | null
Filter by source observation ID
source_trace_idstring | null
Filter by source trace ID

list_dataset_run_items

Вывести список элементов запуска набора данных по идентификатору набора данных и имени запуска.

Параметры

dataset_idstringобязательный
Dataset ID that owns the run items
limitinteger
Items per page (max 100)
output_modeenum
Output format: 'compact' truncates, 'full_json_string' returns full data, 'full_json_file' writes to file
pageinteger
Page number for pagination (starts at 1)
run_namestringобязательный
Dataset run name to list items from

list_dataset_runs

Выводит список запусков для датасета по его имени.

Параметры

dataset_namestringобязательный
The name of the dataset to list runs from
limitinteger
Items per page (max 100)
pageinteger
Page number for pagination (starts at 1)

list_datasets

Вывести все датасеты в проекте с пагинацией. Возвращает метаданные о датасетах: название, описание, количество элементов и временные метки. Аргументы: ctx: Контекстный объект, содержащий контекст жизненного цикла с клиентом Langfuse page: Номер страницы для пагинации (начиная с 1) limit: Максимальное количество элементов на странице (не более 100) Возвращает: Словарь, содержащий: - data: Список объектов метаданных датасетов - metadata: Информация о пагинации (page, limit, total)

Параметры

limitinteger
Items per page (max 100)
pageinteger
Page number for pagination (starts at 1)

list_prompts

Список и фильтрация промптов в проекте. Возвращает метаданные промптов: версии, метки, теги и время последнего обновления. Аргументы: ctx: Контекстный объект с lifespan context и клиентом Langfuse name: Опциональный фильтр по точному имени промпта label: Опциональный фильтр по метке для любой версии tag: Опциональный фильтр по тегу page: Номер страницы для пагинации (начиная с 1) limit: Максимум элементов на странице (макс. 100) Возвращает: Словарь, содержащий: - data: Список объектов метаданных промптов - metadata: Информация о пагинации (page, limit, total)

Параметры

labelstring | null
Filter by label (e.g., 'production', 'staging')
limitinteger
Items per page (max 100)
namestring | null
Filter by exact prompt name
pageinteger
Page number for pagination (starts at 1)
tagstring | null
Filter by tag

list_scores_v2

Выводит баллы из API score v2 с необязательными фильтрами.

Параметры

config_idstring | null
Optional score config ID
data_typestring | null
Optional score data type
environmentstring | null
Optional environment filter
from_timestampstring | null
Optional ISO8601 timestamp lower bound
limitinteger
Items per page (max 100)
namestring | null
Optional score name filter
operatorstring | null
Optional operator filter
pageinteger
Page number for pagination (starts at 1)
queue_idstring | null
Optional annotation queue ID
score_idsstring | null
Optional comma-separated score IDs
session_idstring | null
Optional session ID
sourcestring | null
Optional score source filter
to_timestampstring | null
Optional ISO8601 timestamp upper bound
trace_idstring | null
Optional trace ID
trace_tagsstring | null
Optional comma-separated trace tags
user_idstring | null
Optional user ID filter
valuenumber | null
Optional numeric score value filter

query_metrics

Запрашивает агрегированные метрики (стоимость, задержка, использование токенов, количество, значения оценок) из Langfuse. Обёртка над эндпоинтом метрик Langfuse v2. Используйте для аналитических запросов — «сколько стоила инференция за последние 24 часа в разрезе моделей», «p95 задержка на промпт», «распределение оценок по названиям» — вместо того, чтобы выгружать сырые наблюдения и агрегировать на стороне клиента. Контракты по каждому параметру описаны в описаниях полей выше. Примечания: - Эндпоинт метрик v2 доступен только в Langfuse Cloud; самостоятельные инстансы могут вернуть 404. - Недавно добавленные данные могут задерживаться (задержка приёма OTEL до ~10 минут). - Поля с высокой кардинальностью (id, traceId, userId, sessionId) должны быть фильтрами, а не измерениями.

Параметры

ageinteger | null
Minutes to look back from now (e.g. 1440 for 24h). Used when from_timestamp is omitted; defaults to 1440 (24h) when no time range is given.
dimensionsstring[] | null
Optional fields to group results by, e.g. ['providedModelName']. Do NOT use high-cardinality fields (id, traceId, userId, sessionId) as dimensions — pass them as filters instead.
filtersobject[] | null
Optional filter objects: {'column','operator','value','type', plus 'key' for metadata/object types}. Example: [{'column':'userId','operator':'=','value':'u1','type':'string'}]. See get_metrics_schema for operators and types.
from_timestampstring | null
ISO-8601 start of the time range. Overrides 'age' when provided.
metricsobject[]обязательный
One or more metrics to compute. Each item is {'measure': <name>, 'aggregation': <fn>}, e.g. [{'measure': 'totalCost', 'aggregation': 'sum'}, {'measure': 'latency', 'aggregation': 'p95'}]. Aggregations: sum, avg, count, max, min, p50, p75, p90, p95, p99, histogram.
order_byobject[] | null
Optional ordering: list of {'field': <dimension-or-metric>, 'direction': 'asc'|'desc'}.
output_modeenum
Controls the output format and action. 'compact' (default): Returns a summarized JSON object optimized for direct agent consumption. 'full_json_string': Returns the complete, raw JSON data serialized as a string. 'full_json_file': Returns a summarized JSON object AND saves the complete data to a file.
time_granularityenum | null
When set, results are bucketed by this granularity across the time range (time series).
to_timestampstring | null
ISO-8601 end of the time range. Defaults to now (UTC).
viewenumобязательный
Data view to aggregate over: 'observations' (spans/generations/events — latency, cost, tokens, counts), 'scores-numeric' (numeric/boolean scores), or 'scores-categorical' (categorical scores). Call get_metrics_schema for the full dimension/measure catalog per view.

summarize_route_decisions

Обобщает общие решения маршрутизации для трассировки, сессии, маршрутизатора, провайдера или возможности.

Параметры

ageinteger
Number of minutes to look back (positive integer, max 7 days/10080 minutes)
capability_idstring | null
Optional route-decision metadata capability_id filter
limitinteger
Maximum number of route decisions to summarize from the current page
max_confidencenumber
Confidence threshold used for low-confidence counts
pageinteger
Page number for pagination (starts at 1)
providerstring | null
Optional route-decision metadata provider filter
router_namestring | null
Optional route-decision metadata router_name filter
session_idstring | null
Optional route-decision metadata session_id filter
trace_idstring | null
Optional Langfuse trace ID filter

update_annotation_queue_item

Обновляет статус элемента очереди аннотаций.

Параметры

item_idstringобязательный
Annotation queue item ID
queue_idstringобязательный
Annotation queue ID
statusstringобязательный
New status value

update_prompt_labels

Обновить метки для конкретной версии промпта. Это единственная поддерживаемая мутация для существующих промптов. Предоставленные метки добавляются к версии (существующие метки сохраняются). Метки уникальны для всех версий, а метка 'latest' управляется Langfuse.

Параметры

labelsstring[]обязательный
Labels to add to this version (can be empty to add none). Existing labels are preserved; labels are unique across versions.
namestringобязательный
The name of the prompt to update
versionintegerобязательный
The prompt version to update

Github Сайт сервера

Конфиг для установки сервера

{
  "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"
  }
}

Нужен uvx

Сервер запускается через uvx
Без него ничего работать не будет.

Как установить uvx

FAQ

Для чего этот сервер?

Этот MCP-сервер подключает агентов напрямую к Langfuse, чтобы они сами могли отлаживать сбои, искать медленные запросы и разбираться с ошибками в трейсах. Разработчику не нужно переключаться в дашборд — агент через MCP получает нужные данные о сессиях, исключениях и промптах прямо в рабочем процессе.

Что он умеет?

Сервер читает трейсы, наблюдения и исключения, ищет ошибки по файлам, типам и функциям, считает их количество, разбирает сессии и действия пользователей, находит и обобщает route-решения. Управляет промптами: создаёт текстовые и чат-версии, обновляет метки, получает промпты с зависимостями и без. Работает с датасетами, их элементами и запусками: создаёт, читает, удаляет. Ведёт очереди аннотаций, назначает пользователей, меняет статусы элементов, запрашивает метрики, оценки и схему данных.