Langfuse MCP Server: trace, prompt e dataset

💡 Niente installazione? Vai direttamente su cloud.anythingmcp.com. Accedi, clicca Connectors → Langfuse, inserisci le credenziali, genera una MCP API key e hai finito. Niente Docker, niente git clone, niente server locale.

Langfuse

Leggi un progetto Langfuse con la tua AI: trace LLM, observation e sessioni con costi, token e latenza, metriche nel tempo, score e valutazioni, prompt con versioni ed etichette, dataset, item dei dataset ed esperimenti. Può anche pubblicare versioni di prompt, spostare etichette, aggiungere score e costruire dataset.

Setup

La configurazione richiede circa 3 minuti. Ti serve un progetto Langfuse su Langfuse Cloud (EU, US, Giappone o HIPAA) o su un Langfuse v4 self-hosted.

1. In Langfuse apri il progetto, poi Settings, API Keys, Create new API keys. Usa una chiave di progetto, non una chiave di organizzazione.
2. Copia la chiave pubblica (pk-lf-...) in LANGFUSE_PUBLIC_KEY e la chiave segreta (sk-lf-..., mostrata una sola volta) in LANGFUSE_SECRET_KEY. Il connettore le invia come HTTP Basic auth.
3. Imposta LANGFUSE_HOST sulla regione del progetto, senza barra finale: https://cloud.langfuse.com (EU), https://us.cloud.langfuse.com (US), https://jp.cloud.langfuse.com (Giappone), https://hipaa.cloud.langfuse.com (HIPAA) oppure il tuo indirizzo self-hosted. Le chiavi di una regione non funzionano in un'altra.
4. Installa il connettore ed esegui langfuse_get_project per verificare le chiavi; langfuse_get_health mostra la versione del server.

Costi: nessuno strumento esegue un modello. Il connettore legge e scrive solo dati di Langfuse; i costi che mostra sono quelli che Langfuse ha registrato per le chiamate LLM delle tue applicazioni.

Dati di tracing: in Langfuse v4 un trace è l'insieme delle observation (span, generation, chiamate a tool, eventi) che condividono un traceId, e una sessione è l'insieme dei trace che condividono un sessionId. Il connettore li legge dalla Observations API v2 e dalla Metrics API v2, il percorso di lettura in tempo reale; i vecchi endpoint /traces, /sessions e /metrics/daily sono deprecati (Langfuse Cloud li serve fino al 16 novembre 2026). Gli altri endpoint possono essere indietro di circa 10 minuti rispetto all'acquisizione.

• langfuse_list_observations elenca le righe dalla più recente, sempre limitate da from_start_time e to_start_time. Filtri: type (GENERATION per le chiamate LLM), name, user_id, session_id, trace_id, level (ERROR per gli errori), environment, is_root_observation (true dà una riga per trace) o un filter strutturato. fields sceglie i gruppi di campi core, basic, time, io (input e output), metadata, model, usage (token e costi), prompt, metrics (latenza) e trace_context; il predefinito è core,basic,usage.
• langfuse_get_trace restituisce tutte le observation di un trace con input, output, modello, utilizzo e latenza; la radice non ha parentObservationId e porta input e output del trace.
• langfuse_get_session restituisce per impostazione predefinita una riga per trace di una sessione; root_only: false restituisce tutte le observation.
• langfuse_query_metrics aggrega. query è una stringa JSON con view (observations, scores-numeric, scores-boolean, scores-categorical), metrics (misure come count, latency, totalTokens, totalCost o timeToFirstToken, con le aggregazioni sum, avg, count, max, min, p50, p75, p90, p95, p99), dimensions (ad esempio providedModelName, traceName, promptName, promptVersion, environment, release), timeDimension (per minuto, ora, giorno, settimana o mese), filters, fromTimestamp e toTimestamp. I campi con molti valori come userId e sessionId si possono filtrare ma non raggruppare.

Score: langfuse_list_scores filtra per name, source (API, ANNOTATION, EVAL), data_type, trace, sessione, observation, esperimento, intervallo di valori e di tempo; langfuse_list_score_configs mostra le definizioni degli score. langfuse_create_score aggiunge uno score (numerico, booleano come 0 o 1, categorico o testo) a un trace, observation, sessione o run di esperimento. Viene elaborato in modo asincrono (HTTP 202), e inviare di nuovo lo stesso score_id lo sovrascrive.

Prompt: langfuse_list_prompts elenca i nomi con versioni, etichette e tag; langfuse_get_prompt restituisce la versione con etichetta production, a meno che non si indichi version o label. langfuse_create_prompt_version pubblica una nuova versione di un prompt di testo (con {{variables}}) o di chat, e un nome nuovo crea il prompt; langfuse_update_prompt_labels sposta etichette come production o staging su una versione. Spostare production cambia ciò che le tue applicazioni ricevono, quindi l'AI te lo chiede prima. I nomi con cartelle come support/greeting si passano così come sono.

Dataset ed esperimenti: langfuse_list_datasets, langfuse_get_dataset e langfuse_create_dataset (facoltativamente con schemi JSON per input e output atteso); langfuse_list_dataset_items, langfuse_get_dataset_item e langfuse_upsert_dataset_item (crea un item, o lo aggiorna se item_id esiste; status ARCHIVED lo esclude dai nuovi run). langfuse_list_experiments elenca i run dei dataset e gli esperimenti con i loro score; from_start_time è obbligatorio.

Il server MCP di Langfuse: Langfuse offre anche un server MCP nativo su <LANGFUSE_HOST>/api/public/mcp con la stessa coppia di chiavi, pensato soprattutto per la gestione dei prompt. Questo connettore copre anche i prompt, oltre a dati di tracing, metriche, score e dataset.

Disattivati all'installazione: nessuno. Tutti i 20 strumenti sono attivi; quelli di scrittura aggiungono versioni di prompt, etichette, score, dataset e item, e nessuno cancella dati.

Formati dei dati: gli orari sono ISO 8601, in UTC. I costi sono in USD; nelle observation v2 inputPrice, outputPrice e totalPrice sono stringhe per la precisione decimale, e input e output arrivano come testo JSON. Latenza e tempo al primo token nelle metriche sono in millisecondi.

Paginazione: observation, trace, sessioni, score ed esperimenti usano cursori: l'AI ripassa meta.cursor come cursor finché non manca (observation: 50 righe di default, fino a 1.000). Prompt, dataset, item e score config usano page (da 1) e limit (predefinito 50, al massimo 100); meta.totalPages indica quante pagine esistono.

Limiti: il Langfuse self-hosted deve essere v4 o successivo per gli strumenti di observation e metriche. I dati al di fuori di Observations e Metrics API v2 possono essere in ritardo di circa 10 minuti.

Errori comuni: 400 indica un parametro errato (un JSON di filter o query malformato, un raggruppamento su un campo con molti valori, un limit oltre il massimo); 401 una coppia di chiavi errata o la regione sbagliata; 403 che la chiave non può usare questo endpoint (usa una chiave di progetto); 404 un prompt, dataset o item sconosciuto, o una versione self-hosted senza gli endpoint v2; 429 un limite di frequenza (l'AI attende invece di riprovare in loop).

Il connettore non cancella trace, prompt, dataset o score e non invia trace (lo fanno gli SDK di Langfuse via OpenTelemetry). Annotation queue, LLM connection e amministrazione di organizzazione o SCIM non sono inclusi.

Prerequisiti: LANGFUSE_HOST, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY

Installazione locale del connettore

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Apri http://localhost:3000/connectors/store, scegli Langfuse e inserisci le variabili elencate nei Prerequisiti.

Tool disponibili

Esempi di prompt

• "Quanto sono costate le nostre chiamate LLM per modello e per giorno negli ultimi 7 giorni?"
• "Mostrami le generation di ieri con livello ERROR, con modello, input e output."
• "Mostrami tutta la conversazione della sessione chat-8f21 con input e output di ogni turno."
• "Qual è la latenza p95 per nome di trace questa settimana, e quale è peggiorata?"
• "Pubblica una nuova versione del prompt support/greeting con un tono più cordiale, ma non spostare ancora l'etichetta production."

Prossimi passi

• Collegare a Claude
• Collegare a ChatGPT