ClaudeにLangfuse MCPをつないでプロンプトとトレースを読む

Langfuse(LLMアプリのトレース・プロンプト・評価を扱うオープンソースのプラットフォーム)には、認証付きのMCPサーバーが組み込まれています。Claude Codeに1コマンドで登録すると、「プロジェクト内のプロンプトを一覧して」と頼むだけで listPrompts ツールが呼ばれ、プロンプト管理や観測データの参照を会話に任せられます。

ここでは登録から動作確認まで、読み取り専用に絞る設定、そしてClaude Code向けのスキルやCLIとの使い分けを順に扱います。

Langfuse MCPサーバーで何ができるか

Langfuseのドキュメントでは、MCPサーバーは「AIアシスタントやエージェントがLangfuseのデータをプログラムから扱うための、ネイティブなMCPサーバー」と位置づけられています。APIキーはプロジェクト単位で、サーバーはステートレスです。つないだキーのプロジェクトだけが見えます。

対象の範囲は、Langfuse for Agentsのページに次のように挙がっています。

• 観測データ(observations)とメトリクス
• スコアとスコア設定
• データセット、データセット項目、実行、実行項目
• プロンプト
• コメントとアノテーションキュー
• モデル、メディア、ヘルスチェック

MCPリファレンスのツール一覧を見ると、名前の付き方で役割がおおよそ分かれます。

注目したいのは、ツール一覧に listTraces のような名前が見当たらず、読み取りの単位がobservationになっている点です。トレースの中身を読みたいときは、listObservations に絞り込み条件を渡す形になります。絞り込みの列は getObservationFilterSchema と getObservationFilterValues で調べられます。

読み書きの両方が既定で有効です。MCPクライアント側に許可リスト(allowlist)を設定すれば、書き込み系を止められます。この設定は後の節で扱います。

登録前に決めること

接続先のリージョン

エンドポイントはリージョンごとに分かれ、どれもトランスポートは streamableHttp、認証はAuthorizationヘッダーのBasic認証です。

セルフホストはHTTPSが必須です。リバースプロキシの背後に置く場合は、公開側の Host ヘッダーを保つか、環境変数 LANGFUSE_MCP_ALLOWED_HOSTS に受け付けるホスト名をカンマ区切りで足します。どちらもしないと 403 が返ります。

認証ヘッダーを作る

プロジェクトの設定画面でプロジェクト単位のAPIキーを作成するか、既存のものをコピーします。公開鍵は pk-lf-...、秘密鍵は sk-lf-... の形です。2つを : でつないでbase64にします。

echo -n "pk-lf-your-public-key:sk-lf-your-secret-key" | base64

-n を付けて末尾の改行を入れないのがポイントです。Claude Codeは、MCP設定の headers の値に前後の空白が混じると警告を出します。トークンを貼り付けたときに改行が紛れ込む典型例で、claude mcp list や /mcp の画面に Leading or trailing whitespace in: headers.Authorization の形で出ます。

Claude Codeに登録する

登録はClaude Codeの標準コマンドです。Cloud EUの例を示します。{your-base64-token} を先ほどの出力に置き換えます。

claude mcp add --transport http langfuse \
  https://cloud.langfuse.com/api/public/mcp \
  --header "Authorization: Basic {your-base64-token}"

USリージョンなら us.cloud.langfuse.com、日本リージョンなら jp.cloud.langfuse.com にホストを替えるだけです。ローカル開発用の http://localhost:3000/api/public/mcp も同じ書式で登録できます。

動作確認はClaude Codeに次のように頼みます。

list all prompts in the project

Langfuseのドキュメントによると、このとき listPrompts ツールが使われてプロンプトの一覧が返れば接続できています。日本語で「このプロジェクトのプロンプトを一覧して」と頼んでも構いません。

認証ヘッダーが短寿命トークンで、固定のBasic認証を設定ファイルに置きたくない場合は、動的にヘッダーを作る仕組みがあります。手順はClaude CodeのMCPでheadersHelperを使うにまとめています。ただしLangfuseのドキュメントが案内しているのはBasic認証の固定ヘッダーで、headersHelperとの組み合わせは記載がありません。

登録に失敗するときは、管理設定でプラグイン以外のMCP追加が禁止されている可能性があります。症状と原因はclaude mcp addが失敗する原因で扱っています。

プロンプト管理を会話で進める

Langfuseの「エージェントによるプロンプト管理」のページが挙げている作業は4つです。

• コードベースに埋め込まれたプロンプトをLangfuseへ移す
• プロンプトを取得し、最新の版どうしを比べる
• テキスト型またはチャット型のプロンプトの新しい版を作る
• テスト済みの版にデプロイ用ラベルを付け替えて昇格させる

ツール名に対応づけると、取得は getPrompt、版の作成は createTextPrompt と createChatPrompt、ラベルの付け替えは updatePromptLabels です。依頼文の例を挙げます。

Langfuseのプロンプト一覧から、名前に support を含むものを取得して、
最新2つの版の差分を説明して。変更は加えないで。

production ラベルが付いている版を確認して、staging ラベルの版との違いを
要約して。updatePromptLabels は私が許可するまで呼ばないで。

2つ目の依頼のように、書き込みツールを呼ぶ前に確認を挟む指示を添えておくと、ラベルの付け替えを誤って実行する事故を減らせます。ただし指示は守られる保証のある制限ではないので、本当に止めたいなら次の節の権限設定を使います。

getPromptUnresolved というツールもあります。MCPサーバーのページには getPrompt との違いの説明が載っていないので、使う前にMCPリファレンスで入力スキーマを見比べてください。

トレースと観測データを読む

観測データは listObservations で取得します。ドキュメントには、論理的なルート観測を絞り込むための仕組みが書かれています。

• listObservations は省略可能な真偽値フィルタ isRootObservation を受け取る
• true にすると、物理的な親を持たない観測と、SDKがアプリケーションのルートとして明示した観測に一致する
• 物理的な親による絞り込みは別に残っており、アプリケーションルートは親を持っていても isRootObservation: true に一致しうる
• isRootObservation は listObservations が返す既定のフィールドに含まれる
• getObservationFilterValues も、フィルタ値の列として isRootObservation を扱える

エージェントの1回の実行を1行として数えたいときは、このルートフィルタが起点になります。依頼の例です。

isRootObservation が true の観測を新しい順に10件取得して、
エラーになっているものがあれば要点を教えて。

どの列で絞れるかが分からないときは、先に getObservationFilterSchema を呼ばせます。Claudeが推測で列名を作るより、スキーマを見てから呼ぶ流れのほうが確実です。

読み取りの先に、コメントやスコアの書き込みがあります。LangfuseはAIエージェントが本番の問題を調べ、該当の観測を引き、メトリクスを照会し、チームへのコメントを残し、スコアを付け、回帰テスト用のデータセット項目を用意するところまでを例に挙げています。createComment、createScore、createDatasetRunItem がその書き込み側にあたります。

読み取り専用に絞る

書き込みツールまで開いたままだと、プロンプトの版やラベルが会話の流れで変わりえます。Langfuse側は「許可リストで書き込みを制限する」と案内しているので、Claude Codeの権限設定で表現します。MCPツールの規則名は mcp__<サーバー名>__<ツール名> で、サーバー名に langfuse を使った前提の例です。

{
  "permissions": {
    "allow": [
      "mcp__langfuse__listPrompts",
      "mcp__langfuse__getPrompt",
      "mcp__langfuse__listObservations",
      "mcp__langfuse__getObservation",
      "mcp__langfuse__getObservationFilterSchema",
      "mcp__langfuse__getObservationFilterValues"
    ],
    "deny": [
      "mcp__langfuse__createTextPrompt",
      "mcp__langfuse__createChatPrompt",
      "mcp__langfuse__updatePromptLabels",
      "mcp__langfuse__createScore",
      "mcp__langfuse__createComment"
    ]
  }
}

規則の書き方は公式の権限設定に沿っています。ワイルドカードは mcp__langfuse__* のようにサーバー名の直後から使えます。一方、許可規則に mcp__* のような広いワイルドカードを置くと無視されます。deny に書いたツールは、名前の通りClaudeの文脈から外れるので、書き込みの候補自体が見えなくなります。

注意点が1つあります。例に並べた書き込みツールは一部で、リファレンスには deleteDatasetItem や deleteModel など削除系も並びます。漏れなく止めるなら、allow に読み取り系だけを並べたうえで、未許可のツールは実行時に確認を挟む運用にするのが手堅い構成です。本番プロジェクトに接続するキーは、まず検証用のプロジェクトで試してからにしてください。

スキル・CLI・MCPのどれを使うか

Langfuseは、エージェントがLangfuseを扱う経路を3つ用意しています。ドキュメントの案内を表にします。

Claude Codeはシェルを実行できるので、Langfuseのドキュメントの基準ではMCPよりスキルが推奨されます。MCPサーバーのページ自体も、CLIツールを入れてbashを実行できる環境ならAgent Skillを使うよう案内しています。それでもMCPを選ぶ理由が立つのは、たとえば次のような場面です。

• 共有するClaude環境で、ローカルにCLIを入れさせたくない
• Claude Code以外のクライアントでも同じ設定を使い回したい
• 権限設定でツール単位に許可・拒否を管理したい

スキルには、Claude Code向けの公式プラグインがあります。Claude Codeのマーケットプレイスのページによると、トレースの設定、ハードコードされたプロンプトのLangfuseへの移行、CLIによるトレースとデータセットの照会、CI/CDでの実験ゲートの設定、ドキュメントの検索を扱います。

スキルの導入方法は、手動ならLangfuseのドキュメントにある次のコマンドです。

npx skills add langfuse/skills --skill "langfuse"

スキルとMCPは併用できます。ただしどちらも同じ操作ができる場面では、エージェントがどちらを選ぶか指示しないと揺れます。「データの照会はMCP、アプリのコード変更はスキル」のように役割を依頼文で分けると安定します。スキルとMCPそれぞれの性質はSkillsとMCPの違いで比べています。

つまずきやすい点

• エンドポイントとキーの組が合っていない: キーはプロジェクト単位です。キーを作ったリージョンまたはセルフホスト環境のエンドポイントを指定します。
• キーを共有ファイルに書いてしまう: --header に渡した値は設定に保存されます。チームで共有するリポジトリのプロジェクトスコープに置くと、秘密鍵が混じる設定ファイルを配ることになります。個人のスコープで登録するか、秘密情報を共有しない仕組みを選びます。
• 変更を見落とす: 書き込みを許可した状態では、ラベルの付け替えがそのまま本番のプロンプトに反映されます。移行や昇格の作業の前に、現在のラベルの状態を取得させて記録しておくと戻せます。

まとめ

Claude CodeでLangfuseを扱う入口は、スキルが第一候補でMCPは補助、というのがLangfuse自身の整理です。MCPが向くのは、CLIを入れずにツール単位で権限を管理したい環境です。その場合も、まず読み取り系だけを許可して listPrompts で接続を確かめ、プロンプトの版の作成やラベルの付け替えは検証用プロジェクトで動きを見てから広げるのが安全な順序です。

LLMアプリ側の計測をOpenTelemetryで組むなら、Agent SDKをOpenTelemetryで可観測化する実装ガイドも参考になります。