Langfuse API

langfuse-api-mcp

AI エージェントが Langfuse の公開 API 全体にアクセスできる MCP サーバーです。あらゆるリージョンの Langfuse Cloud と セルフホスト インスタンスで動作します。独自の認証局（CA）で TLS 通信を再署名する企業ネットワークでの実行を想定して構築されています。

重要

ステータス：プレアルファ、リリース v0.2.0（semver 0.x：現時点では安定性を保証しません。最初のリリースは v0.1.0 でした）。ループバック HTTP トランスポートのように 予定 と記載されているものを除き、以下の機能はすべて現在利用できます。

目次： 概要 · ツール · ユーザースキル · インストールと実行 · クライアント設定 · 設定 · セキュリティモデル · トラブルシューティング · 詳細

---

概要

AI ツール（Claude Code、Claude Desktop、Cursor、VS Code、Codex、…）がマシン上で起動する、小規模でステートレスなプログラムです。エージェントとは Model Context Protocol で、Langfuse とは HTTPS で通信します。これにより、エージェントは次の操作を行えます。

• トレース、オブザベーション、セッション、エラー、レイテンシ、コストを調査する。
• プロンプト、データセット、実験、スコア、メトリクス、モデル、コメント、アノテーションキューを読み取る。
• プロンプトラベルの昇格、スコアの作成、データセットの編集などの変更を行う。これは 書き込みを有効にした場合にのみ 動作します（セキュリティモデルを参照）。

flowchart LR
  A[AI agent<br/>Claude Code, Cursor, …] -- MCP over stdio --> S[langfuse-mcp<br/>on your machine or in Docker]
  S -- HTTPS + your corporate CA --> P{{Corporate proxy<br/>optional}}
  P --> L[(Langfuse<br/>Cloud or self-hosted)]
  S -. reads .-> C[/Your config:<br/>keys, host, CA files/]
  classDef local fill:#e0f2fe,stroke:#0369a1,color:#0c4a6e;
  classDef remote fill:#fef3c7,stroke:#b45309,color:#78350f;
  class A,S,C local;
  class L,P remote;

使用する場面

状況	このサーバーを使いますか？
会社のネットワークがカスタムルート CA で TLS を検査しており、公式の Langfuse MCP または CLI で self-signed certificate in certificate chain / unable to get local issuer certificate が発生する	はい。 これがこのプロジェクトの主な目的です。
明示的に許可しない限り、エージェントが Langfuse のデータを変更できないようにしたい	はい。 デフォルトは読み取り専用で、サーバーは経由するすべての呼び出しに対してこれを強制します。キーはエージェント自身の環境変数に設定しないでください。そうしないと、別のツールがキーを直接使用できてしまいます：キーをエージェントの環境変数に設定しない。
内部 CA またはプロキシの背後でセルフホスト Langfuse を実行している	はい。
マシンに Node.js や Python のランタイムを用意せず、単一のバイナリを使いたい	はい。
エージェントに Langfuse の ドキュメント だけが必要	いいえ。公式のドキュメント MCP（https://langfuse.com/api/mcp）を使用してください。
エージェントがシェルコマンドを実行でき、ネットワークで TLS インターセプトが行われない	どちらでも構いません。Langfuse は公式の CLI とエージェントスキルも提供しています。

公式 Langfuse MCP との違い

	公式プロジェクトの MCP（<host>/api/public/mcp）	このサーバー
実行場所	リモート、Langfuse 内	ローカル（バイナリまたは Docker）
カスタム CA／企業プロキシ	MCP クライアントのランタイムによります。ドキュメント化された設定はありません	明示的な設定に加え、システムにすでに設定されている CA 関連の環境変数を自動的に取得します
書き込み	デフォルトで有効。制限するには、クライアント側の許可リストを設定します	デフォルトでは無効。有効にするまで、書き込みツールは存在しません。
API の対応範囲	厳選されたツール群	Langfuse のデプロイ環境が実際に応答するすべての操作。古いセルフホスト版では従来の API、新しい版では新しい API が利用されます。ただし、トレースの取り込みと組織管理者による変更（プロジェクト、API キー、ユーザーの作成／削除）は対象外です。起動時に自動検出され、設定は不要です（デプロイプロファイル）

ツール

Langfuse API には、対象となる操作が約 100 個あります。操作ごとに 1 つのツールを用意するとエージェントのコンテキストウィンドウを使い切ってしまうため、このサーバーでは少数のツールを公開しています。

ツール	機能	利用可能
search_operations	デプロイ環境で提供されている Langfuse の操作を一覧表示します。キーワードによる絞り込みも可能です（書き込みモードでは、各書き込み操作の HTTP メソッドと破壊的操作かどうかも表示します）	常時
describe_operation	デプロイ環境の Langfuse バージョンで提供されている 1 つの操作のパラメーターを返します（それに加え、お使いのバージョンにそのフィルターがない場合にサーバーが適用するフィルターも返します。また、書き込みモードでは、リクエストボディのスキーマ（デプロイ環境の Langfuse バージョンのもの）、破壊的操作かどうか、および comments_create と scores_create のリクエストボディの入力方法も返します）	常時
execute_read	ID で 読み取り操作（HTTP GET）を実行し、信頼できないデータのエンベロープに Langfuse の JSON を格納して返します。古い Langfuse が scores_get-many の traceId または legacy_observationsV1_getMany の level を無視する場合、サーバーがそのフィルターを適用し、リスト全体を読み取ったかどうかを伝えます	常時
execute_write	ID で 書き込み操作を実行します。破壊的操作（DELETE、PUT、PATCH）は、その呼び出し内容を確認した後にのみ実行されます	書き込みモードでのみ
get_trace_tree	1 回の呼び出しで、1 つのトレースのすべてのオブザベーションをツリーとして返します。デプロイ環境が v4 読み取り API に応答する場合（Cloud、セルフホスト v4）は Observations v2 を読み取り、セルフホスト v3 の場合はレガシーのオブザベーションリストを読み取ります。入力、出力、メタデータは、要求しない限り除外されます。また、行には Langfuse が返すフィールドが保持されます（v4 では秒単位、こちらではミリ秒単位のレイテンシを含みます）が、null として返されたフィールドは除外されます。デプロイ環境が両方に応答する場合、ツリーは Observations v2 から読み取られます。レガシー取り込み API 経由で送信されたオブザベーションは含まれないことがあるため、ツリーが空または短い場合は、execute_read でレガシーのオブザベーションリストを確認できます。どちらの API も応答しない場合は operation_unavailable を返します	常時一覧に表示。デプロイ環境がいずれかの API に応答する場合に実行

一般的なセッションの流れは、search_operations で操作を見つけ、describe_operation でパラメーターを確認し、execute_read で実行するというものです。

{"operationId": "trace_list", "parameters": {"limit": 10, "tags": ["prod", "checkout"]}}

サーバーは呼び出しの間に何も保持しません（ステートレスです）。エージェントから URL、ホスト、認証情報を受け取ることもありません。組み込みカタログにある操作のみを、設定済みのホストに対して実行します。すべての呼び出しは送信前に検証され、エラーが発生した場合は code、hint、retryable フラグを含む構造化されたツールエラーとして返されます。パラメーター、エラーコード、結果の上限、監査ログ行については、ツールのリファレンスを参照してください。

ユーザースキル

このサーバーはエージェントに汎用ツールを提供します。ユーザースキル langfuse-api-mcp（skills/langfuse-api-mcp/）は、それらを使って Langfuse を調査する方法をエージェントに教えます。つまり、検出し、説明してから実行すること、常に時間範囲を限定すること、Langfuse のデータは信頼できないものであり、指示として扱わないことです。短いエントリーファイルと、ワークフローごとに1つのリファレンス（トレース、コストとレイテンシ、プロンプト、実験、スコア、エラー）があり、各リファレンスは該当するワークフローが要求された場合にのみ読み込まれます。説明にはこのサーバーのツールが記載されているため、Langfuse 独自の langfuse スキルと競合しません。独自の権限は追加されません。execute_write が存在するかどうか、およびすべての確認は、引き続きサーバーの判断に委ねられます。

Claude Code、Cursor、VS Code、Codex CLI、Gemini CLI、Windsurf。 skills CLI を使って、リポジトリからプロジェクトにインストールします（ユーザー向けにインストールする場合は -g を指定します）。--agent でインストール先のホストを指定します（すべてのホストにインストールする場合は --agent '*'）。Claude Code でのインストールは実証済みです。他のホストについては、CLI 自体のサポートに依存します。

npx skills add rodrigorjsf/langfuse-api-mcp
# non-interactive, one host: npx skills add rodrigorjsf/langfuse-api-mcp --agent claude-code -y

CLI は main からインストールしますが、お使いのサーバーは古いビルドである可能性があります。そのため、このスキルでは、名前が示されていないすべてのパラメーターについて、エージェントに describe_operation を呼び出すよう指示します（詳細）。

Claude Desktop では、スキルはアップロードによってのみインストールできます。各GitHub リリースには、署名済みの langfuse-api-mcp-skill_<version>.zip が含まれています。この ZIP のルートは langfuse-api-mcp/ フォルダーです。Claude Desktop の「Customize」>「Skills」からアップロードしてください。

インストールと実行

チャネル	プラットフォーム	必要なもの
npx	Linux、macOS、Windows × x64、arm64	npm を含む Node.js
リリースアーカイブ	Linux、macOS、Windows × amd64、arm64	なし
Docker	linux/amd64、linux/arm64。stdio のみ	Docker
Claude Desktop（MCPB）	macOS、Windows	Claude Desktop
go install	Go 対応のすべてのプラットフォーム	Go 1.21 以降

go install を除くすべてのチャネルは、署名済みであるか npm のプロベナンス情報を付与しています。実行するものを検証するを参照してください。このサーバーは、MCP Registry に io.github.rodrigorjsf/langfuse-api-mcp としても登録されています。各チャネルに含まれるものとビルド方法については、インストールリファレンスを参照してください。

npx

MCP クライアントで、サーバーを npx -y langfuse-api-mcp として設定します（バージョンを固定する場合は langfuse-api-mcp@<version> を指定します）。必要なのは npm を含む Node.js のみです。パッケージには Go バイナリが含まれているため、インストール時に何かがダウンロードされることはなく、インストールスクリプトも実行されません。お使いのクライアントの設定例はクライアント設定を参照してください。

リリースアーカイブ

各GitHub リリースには、ターゲットごとに1つのアーカイブ langfuse-mcp_<version>_<os>_<arch>.tar.gz（Windows では .zip）と、checksums.txt が含まれています。gh または curl でダウンロードし、アーカイブを checksums.txt と照合してから展開してください（以下は amd64 の Linux の例です。<version> は先頭の v を除いたリリース番号です。例：0.2.0）。

version=<version>
archive="langfuse-mcp_${version}_linux_amd64.tar.gz"
gh release download "v$version" -R rodrigorjsf/langfuse-api-mcp -p "$archive" -p checksums.txt
# or: curl -fsSLO "https://github.com/rodrigorjsf/langfuse-api-mcp/releases/download/v$version/$archive"
#     curl -fsSLO "https://github.com/rodrigorjsf/langfuse-api-mcp/releases/download/v$version/checksums.txt"
awk -v f="$archive" '$2 == f' checksums.txt | sha256sum -c -   # macOS: … | shasum -a 256 -c -
tar -xzf "$archive"

Windows（PowerShell）では、ハッシュを照合して ZIP を展開します。

$archive = "langfuse-mcp_<version>_windows_amd64.zip"
(Get-FileHash $archive -Algorithm SHA256).Hash.ToLower()   # must equal the line for $archive in checksums.txt
Expand-Archive $archive -DestinationPath langfuse-mcp

その後、展開したバイナリを MCP クライアントに指定します（クライアント設定を参照）。バイナリは公証も Authenticode 署名もされていません。ブラウザーではなく curl または gh でダウンロードしてください。またはブラウザーでダウンロードした場合を参照してください。

Docker

-eでキーとベース URLを渡し、-iはそのままにしてください（サーバーは標準入力と標準出力を介してMCPを使用します）。

docker run -i --rm \
  -e LANGFUSE_PUBLIC_KEY -e LANGFUSE_SECRET_KEY -e LANGFUSE_BASE_URL \
  ghcr.io/rodrigorjsf/langfuse-api-mcp:<version>

値を指定せずに-e NAMEを指定すると、dockerを実行する環境の変数が渡されるため、キーがコマンドラインに表示されることはありません。企業のCAの背後で使用する場合は、CAファイルを読み取り専用でマウントし、LANGFUSE_CA_CERTにそのファイルを指定してください。ファイルはすべてのユーザーが読み取り可能である必要があります（イメージはあなたのユーザーとして実行されません）。

docker run -i --rm \
  -e LANGFUSE_PUBLIC_KEY -e LANGFUSE_SECRET_KEY -e LANGFUSE_BASE_URL \
  -e LANGFUSE_CA_CERT=/certs/corp.pem -v /path/to/corp.pem:/certs/corp.pem:ro \
  ghcr.io/rodrigorjsf/langfuse-api-mcp:<version>

MCPクライアントでは、commandをdockerに、argsを上記のリストに設定します。キーはクライアントのenvブロックに設定し、args内で-e NAME=valueとして指定しないでください。イメージは標準入出力のみを提供します。

Claude Desktop（MCPB）

GitHubリリースからlangfuse-mcp_<version>.mcpb（macOS、Windows amd64）をダウンロードし、ダブルクリックするか、Claude Desktopにドラッグします。インストールダイアログで次の項目を尋ねられます。

項目	必須	設定先
Langfuse public key	はい。OSのキーチェーンに保存され、マスクされます	LANGFUSE_PUBLIC_KEY
Langfuse secret key	はい。OSのキーチェーンに保存され、マスクされます	LANGFUSE_SECRET_KEY
Langfuse base URL	はい	LANGFUSE_BASE_URL
CA certificate	いいえ。ファイル選択ダイアログを使用します	LANGFUSE_CA_CERT

ダイアログに書き込みモードのオプションがないのは意図的です。書き込みを有効にするには、設定ファイルでLANGFUSE_MCP_ALLOW_WRITES=trueを設定してください。プロキシやリクエスト制限など、その他の設定も設定ファイルで行います。

go install

リリース（@v0.2.0または@latest）またはコミット（@mainまたはコミットハッシュ）をインストールします。Go 1.21以降が必要です（モジュールのtoolchainディレクティブにより、必要なGo 1.27ツールチェーンが取得されます）。

go install github.com/rodrigorjsf/langfuse-api-mcp/cmd/langfuse-mcp@<version>

バイナリは$(go env GOPATH)/binに配置されます。チェックアウトからは、go build -o langfuse-mcp ./cmd/langfuse-mcpでビルドできます。

クライアントの設定

MCPクライアントごとに1つのスニペットを使用します。すべてのスニペットではnpxを使用します。リリースアーカイブを使用するには、"command": "npx", "args": ["-y", "langfuse-api-mcp"]を"command": "/absolute/path/to/langfuse-mcp"に置き換え、argsを指定しないでください（Windowsではlangfuse-mcp.exe）。

各クライアントは、それぞれの環境からサーバーを起動します。シェルの変数を引き継がないクライアントもいくつかあります。そのため、すべてのスニペットで、サーバーに必要な3つの変数をクライアント独自のenv機構で指定しています。キーを設定できるのはここだけです。pk-lf-...とsk-lf-...はそれぞれキーを表します。クライアントの環境からキーを読み込むスニペット（${VAR}、${env:NAME}、$NAME、env_vars）を使う場合は、クライアントの起動時にキーがエクスポートされている必要があります。また、エージェント独自のシェルもそこからキーを引き継ぎます。詳しくはキーをエージェントの環境変数から除外するを参照してください。クライアントごとの落とし穴とトレードオフについては、MCPクライアントの詳細を参照してください。

Claude Code — 検証済み

キーは--envで渡します。最後の--envとサーバー名の間に、オプション（ここでは--transport stdio）を置く必要があります。キーは~/.claude.jsonに保存されます。

claude mcp add \
  --env LANGFUSE_PUBLIC_KEY=pk-lf-... \
  --env LANGFUSE_SECRET_KEY=sk-lf-... \
  --env LANGFUSE_BASE_URL=https://cloud.langfuse.com \
  --transport stdio langfuse -- npx -y langfuse-api-mcp

プロジェクトの.mcp.jsonでは、Claude Codeがenv内の${VAR}と${VAR:-default}を展開します。

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-api-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "${LANGFUSE_PUBLIC_KEY}",
        "LANGFUSE_SECRET_KEY": "${LANGFUSE_SECRET_KEY}",
        "LANGFUSE_BASE_URL": "${LANGFUSE_BASE_URL:-https://cloud.langfuse.com}"
      }
    }
  }
}

Claude Desktop

キーをOSのキーチェーンに保存するMCPBバンドルの使用をおすすめします。Claude Desktopがサーバーに渡す環境変数は限られています。手動で設定するには、claude_desktop_config.json（macOSでは~/Library/Application Support/Claude/、Windowsでは%APPDATA%\Claude\）を編集し、キーをenvに設定します。また、commandには絶対パスを指定してください（macOSではwhich npx、Windowsではwhere npx）。

{
  "mcpServers": {
    "langfuse": {
      "command": "/absolute/path/to/npx",
      "args": ["-y", "langfuse-api-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-...",
        "LANGFUSE_SECRET_KEY": "sk-lf-...",
        "LANGFUSE_BASE_URL": "https://cloud.langfuse.com"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json（すべてのプロジェクト）または.cursor/mcp.json（単一のプロジェクト）で、各変数を${env:NAME}を使って渡します。Cursor自体も、これらの変数を設定した状態で起動する必要があります。

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-api-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "${env:LANGFUSE_PUBLIC_KEY}",
        "LANGFUSE_SECRET_KEY": "${env:LANGFUSE_SECRET_KEY}",
        "LANGFUSE_BASE_URL": "${env:LANGFUSE_BASE_URL}"
      }
    }
  }
}

VS Code（GitHub Copilot）

キーを"password": trueを指定したinputsとして宣言します。サーバーの初回起動時にVS Codeがキーを尋ね、安全に保存します。ファイルではmcpServersではなくserversを使用します。

{
  "inputs": [
    { "type": "promptString", "id": "langfuse-public-key", "description": "Langfuse public key", "password": true },
    { "type": "promptString", "id": "langfuse-secret-key", "description": "Langfuse secret key", "password": true }
  ],
  "servers": {
    "langfuse": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "langfuse-api-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "${input:langfuse-public-key}",
        "LANGFUSE_SECRET_KEY": "${input:langfuse-secret-key}",
        "LANGFUSE_BASE_URL": "https://cloud.langfuse.com"
      }
    }
  }
}

Codex CLI

Codex はサーバーの起動前に環境変数をクリアします。~/.codex/config.toml（またはプロジェクトの .codex/config.toml）にある env_vars に変数名を列挙してください。Codex は自身の環境からその値を引き継ぎます。

[mcp_servers.langfuse]
command = "npx"
args = ["-y", "langfuse-api-mcp"]
env_vars = ["LANGFUSE_PUBLIC_KEY", "LANGFUSE_SECRET_KEY", "LANGFUSE_BASE_URL"]

Gemini CLI — 起動確認済み

Gemini CLI は、名前に KEY、SECRET、TOKEN のいずれかを含む変数をすべて削除します。そのため、~/.gemini/settings.json（または信頼済みフォルダーでのみ読み込まれる、プロジェクトの .gemini/settings.json）にある env にキーを指定してください。

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-api-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "$LANGFUSE_PUBLIC_KEY",
        "LANGFUSE_SECRET_KEY": "$LANGFUSE_SECRET_KEY",
        "LANGFUSE_BASE_URL": "$LANGFUSE_BASE_URL"
      }
    }
  }
}

Windsurf

~/.config/devin/mcp_config.json（macOS および Linux。Windows では %APPDATA%\devin\mcp_config.json）で ${env:NAME} を使って各変数を引き継ぎます。

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-api-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "${env:LANGFUSE_PUBLIC_KEY}",
        "LANGFUSE_SECRET_KEY": "${env:LANGFUSE_SECRET_KEY}",
        "LANGFUSE_BASE_URL": "${env:LANGFUSE_BASE_URL}"
      }
    }
  }
}

設定

設定は環境変数から取得し、続いて機密情報以外の設定については任意の設定ファイルから取得します。環境変数の設定が優先されます。無効な値がある場合、キーを決して表示せず、変数名を含むエラーを1つ表示して起動を停止します。すべてのルール、デフォルト値、起動ログについては、設定リファレンスを参照してください。

接続

変数	必須	説明
LANGFUSE_PUBLIC_KEY	はい	プロジェクトの公開キー（pk-lf-…）。環境変数でのみ設定します。
LANGFUSE_SECRET_KEY	はい	プロジェクトのシークレットキー（sk-lf-…）。環境変数でのみ設定します。ログに記録されることはなく、エージェントに返されることもありません。
LANGFUSE_BASE_URL	はい	Langfuse のホスト。絶対 https URL（ループバックホストの場合のみ http）。LANGFUSE_HOST はエイリアスとして使用できます。意図的にデフォルト値はありません。

クラウドリージョン：EU https://cloud.langfuse.com · US https://us.cloud.langfuse.com · JP https://jp.cloud.langfuse.com · HIPAA https://hipaa.cloud.langfuse.com。キーは、作成されたリージョンでのみ使用できます。

証明書とプロキシ

変数	説明
LANGFUSE_CA_CERT	1つ以上の CA 証明書を含む PEM ファイル
LANGFUSE_CA_CERTS_PATH	PEM ファイルのディレクトリ
SSL_CERT_FILE、SSL_CERT_DIR、NODE_EXTRA_CA_CERTS、REQUESTS_CA_BUNDLE、CURL_CA_BUNDLE（環境から継承）	すでに設定されていれば自動的に読み込まれます。そのため、ほかのツール用にエクスポートした CA もここで使用できます
LANGFUSE_MCP_IGNORE_AMBIENT_CA	true = 環境から継承した変数を読み込みません
HTTPS_PROXY、HTTP_PROXY、NO_PROXY（および小文字表記）	標準のプロキシ変数。http、https、socks5 または socks5h のプロキシに対応。Basic 認証のみ

信頼するルート証明書 = オペレーティングシステムの証明書ストア + 上記の各ソースから取得したすべての CA。TLS 1.2 が最小バージョンです。**証明書の検証を無効にするオプションはありません。**サーバーは Windows または macOS のプロキシ設定も PAC ファイルも読み込みません。プロキシの確認方法を参照してください。

リクエスト制限

変数	デフォルト	許可される値	説明
LANGFUSE_MCP_RATE_LIMIT	Langfuse Cloud ホストでは 30、それ以外のホストでは 1000	1～60000 の整数	リトライを含め、サーバーが1分間に送信する Langfuse リクエストの最大数です。有料の Cloud プランでは、プランの上限まで引き上げてください。
LANGFUSE_MCP_MAX_CONCURRENCY	4	1～64 の整数	同時に処理中となる Langfuse リクエストの最大数です。

結果サイズの上限

変数	デフォルト	許可される値	説明
LANGFUSE_MCP_MAX_RESULT_BYTES	65536（64 KiB）	16384～1048576 の整数	1つのツール結果に含められる最大バイト数です。JSON のテキスト形式と構造化コンテンツ形式という2つのコピーそれぞれについて数えます。上限を超えた結果では、まず最大のテキスト値を短縮し（各値の末尾に … [clipped] を付加）、すべての行を残します。それでも足りない場合に限り、残りの行を省略して truncated と表示します。検出ツールの結果（describe_operation、search_operations）もこの上限内に収められます。その場合、ボディスキーマから説明が削除され、操作インデックスからは末尾のエントリーが削除されます。MCP ホスト側にも結果表示の上限があり、さらに低い場合があります。Claude Code では約 100 KB の結果がインライン表示されなかったため、設定した上限をホストで表示できる場合にのみ引き上げてください。

動作

変数	デフォルト	意味
LANGFUSE_MCP_ALLOW_WRITES	false	true にすると書き込みモードが有効になり、execute_write が登録されます。値は true または false のみです。エージェントに Langfuse のデータを変更させる場合を除き、無効のままにしてください。
LANGFUSE_MCP_TRANSPORT	stdio	http にすると、ベアラートークンで保護された Streamable HTTP を 127.0.0.1 のみで起動します （予定）

サーバーは起動時に Langfuse のバージョンと提供する操作を検出します。設定は不要です（デプロイプロファイル）。Langfuse のアップグレード後は、サーバーを再起動してください。

設定ファイル（シークレット以外の設定）

CA、ホスト、プロキシ、制限、結果サイズの上限、または書き込みモードをすべてのクライアントに一度に設定するには、OS 標準の設定場所にある設定ファイルに記述します。

OS	パス
Linux	~/.config/langfuse-mcp/config.env（または $XDG_CONFIG_HOME/langfuse-mcp/config.env）
macOS	~/Library/Application Support/langfuse-mcp/config.env
Windows	%AppData%\langfuse-mcp\config.env

# KEY=VALUE per line; environment variables win over this file
LANGFUSE_BASE_URL=https://langfuse.internal.example.com
LANGFUSE_CA_CERT=/etc/ssl/private/corp-root.pem
HTTPS_PROXY=http://proxy.example.com:8080

値はそのまま解釈されます。引用符は使用せず、${VAR} の展開も行われません。このファイルにキーを記述することはできません。LANGFUSE_PUBLIC_KEY または LANGFUSE_SECRET_KEY が含まれている場合、サーバーは起動を拒否します。ファイルの読み込み方法。

証明書のシナリオ

状況	対応方法
IT 部門が社内のルート CA を OS のストアにインストールしている（管理対象の Windows および macOS マシンでは一般的）	対応は不要です。OS のストアが使用されます。
.pem / .crt ファイルを受け取った	LANGFUSE_CA_CERT=/path/to/corp-root.pem
証明書のフォルダーを受け取った	LANGFUSE_CA_CERTS_PATH=/path/to/certs/
マシンで他のツール用に NODE_EXTRA_CA_CERTS または REQUESTS_CA_BUNDLE がすでに設定されている	対応は不要です。自動的に読み込まれます。
HTTP プロキシを経由している	環境変数または設定ファイルで HTTPS_PROXY（および内部ホスト用の NO_PROXY）を設定します。プロキシを参照してください
Docker	ファイルを読み取り専用でマウントし、変数で指定します：-v /path/to/corp.pem:/certs/corp.pem:ro -e LANGFUSE_CA_CERT=/certs/corp.pem（Dockerを参照）。イメージが信頼するのは、ベースイメージの CA バンドルとこのファイルのみです。それ以外は信頼しません。

会社のルート CA を PEM 形式で取得します。

OS	方法
Windows	certmgr.msc → 信頼されたルート証明機関 → Base-64 X.509（.CER）としてエクスポート
macOS	キーチェーンアクセス → システムルート／システム → 証明書を選択 → ファイル → 書き出す → .pem
Linux	通常は /usr/local/share/ca-certificates/ または /etc/pki/ca-trust/source/anchors/

起動ログの CA sources loaded には、読み込まれた CA ソース（パスと件数が表示され、内容は表示されません）が一覧表示されます。このログを使って設定を確認してください。

セキュリティモデル

• オプトインしない限り読み取り専用です。 LANGFUSE_MCP_ALLOW_WRITES=true を設定しない限り、書き込みツールは存在しません。execute_read は GET 操作のみを実行します。ツールセットは起動時に固定されます。
• 書き込みモードでは、破壊的な呼び出しのたびに確認が必要です。 書き込みを有効にすると、作成（POST）はそのまま実行され、DELETE、PUT、PATCH はすべて、クライアントのフォームで該当する呼び出しを確認した後にのみ実行されます。フォームによる確認機能のないクライアントでは、破壊的な操作を一切実行できません。確認を省略する設定はありません。書き込みが自動的に再試行されることはありません。
• キーはサーバー内に保持されます。 サーバーの環境からのみ読み取られ、エージェントから受け取ることはなく、ログにも記録されず、結果として返されることもありません。
• 信頼できないデータにはラベルが付けられます。 Langfuse のコンテンツは、データであることを示すエンベロープに入れてエージェントに渡されます。隠れた Unicode 文字や制御文字は除去されます。これには、トレースの入力または出力の JSON テキスト内でエスケープ文字として記述されている場合も含まれます。
• 検証済みの TLS のみを使用します。 OS の証明書ストアとお客様の CA を使用し、TLS 1.2 以上を必須とします。検証を省略するオプションはありません。

推奨事項：エージェント専用の Langfuse キーを作成し、有効期限を設定してください。また、必要な場合を除き、書き込みを無効にしておいてください。

すべての保証とその実施方法、書き込み時の確認の詳細、リリース署名の検証方法については、セキュリティモデルのリファレンスを参照してください。脆弱性を発見した場合は、公開イシューではなく、非公開で報告してください。SECURITY.mdを参照してください。

エージェントの環境からキーを除外する

書き込みゲート（書き込みモードがオフであること、および書き込みモードでの破壊的な呼び出しごとの確認）が対象とするのは、このサーバーを経由する呼び出しのみです。同じキーを持つ別のプロセスを検知したり、停止したりすることはできません。MCP クライアントの起動時の環境にキーがあると、エージェントが実行するすべてのシェルコマンドとツールにキーが引き継がれます。そのため、たとえばこのサーバーの起動に失敗してエージェントが別の方法を探す場合、シェルを使えるエージェントはキーを使って Langfuse の CLI や curl を呼び出し、確認なしにデータを変更できます。シェルツールだけを拒否しても不十分です。その環境を引き継いでプロセスを起動するツール（スクリプトランナー、コードインタープリター、プラグインなど）も同じことができます。

• キーはシェルではなく、クライアント独自のサーバーごとの設定に保存してください。Claude Code では claude mcp add --env（~/.claude.json に保存）、Claude Desktop では MCPB バンドル（OS のキーチェーン）、VS Code では "password": true を指定した inputs、またはリポジトリに含めないクライアントの env ブロックに直接値を記述します。
• MCP クライアントを起動するシェルでは、LANGFUSE_PUBLIC_KEY や LANGFUSE_SECRET_KEY を決してエクスポートしないでください。クライアント設定にある ${VAR} 形式のスニペットを使うには、この設定が必要です。そのため、エージェントがコマンドを実行できない場合に限り使用してください。
• エージェントは引き続きお客様のユーザーとして実行されるため、キーを含むファイルを読み取れる可能性があります。クライアントに権限ルールがある場合は、エージェントによるそのファイルの読み取りを拒否してください。厳格に制限するには、エージェントがコマンドを一切実行できないようにしてください。

トラブルシューティング

すべての失敗は、安定した code（例：langfuse_unauthorized、langfuse_rate_limited、tls_untrusted_certificate）、hint、retryable フラグを含む構造化エラーとしてエージェントに返されます。サーバーが接続をクラッシュさせたり、シークレットを返したりすることはありません。すべてのコードについては、ツールリファレンスを参照してください。

症状	考えられる原因	対処方法
サーバーが起動せず、クライアントに失敗したと表示される	ホストまたはキーが未設定、あるいは設定が無効です。サーバーは終了コード 1 で終了し、変数名を示す JSON エラー行を stderr に出力します	クライアントの MCP ログでその行を確認し、クライアントの設定にあるお使いのクライアント向けの設定例を確認してください
Claude Code が起動時（/mcp）にサーバーを failed と表示し、そのセッションではサーバーなしで実行される	v0.1.0 より前にビルドされたサーバーを Claude Code 2.1.283 で使用しており、Langfuse の起動時プローブへの応答が遅い	v0.1.0 以降を使用してください。Claude Code 2.1.284 では自動的に復旧します（詳細）
x509: certificate signed by unknown authority、またはツールエラー tls_untrusted_certificate	社内 CA が信頼プールにありません	LANGFUSE_CA_CERT（PEM ファイル）または LANGFUSE_CA_CERTS_PATH（ディレクトリ）を設定し、起動ログに「CA sources loaded」と表示されることを確認してください
ツールエラー network_error	ホスト、DNS、またはプロキシの問題です	LANGFUSE_BASE_URL のホストを確認してください。プロキシ経由の場合は HTTPS_PROXY／NO_PROXY も確認します。起動ログの proxy 行に、使用中のプロキシが表示されます
ツールエラー langfuse_unauthorized（HTTP 401）	キーペアが間違っているか、別のリージョンのキーです	LANGFUSE_PUBLIC_KEY と LANGFUSE_SECRET_KEY、および LANGFUSE_BASE_URL がキーのリージョンのホストであることを確認してください。キーはそれぞれのリージョンでのみ機能します
ツールエラー langfuse_rate_limited（HTTP 429）	Langfuse のレート制限に達しました	Langfuse が Retry-After で示した待機時間が 60 秒のリクエスト期限内に収まる場合、読み取り操作はすでに一度再試行されています。再度呼び出す前に retryAfterSeconds の秒数だけ待機してください（0：Langfuse が待機時間を指定していないため、バックオフしてください）。一部のプランでは、メトリクス操作に少量の日次上限があります。サーバー独自の制限（リクエスト制限）は、Langfuse Cloud ホストではデフォルトで毎分 30 リクエストです
ツールエラー timeout、retryable: true	サーバー独自のリクエスト制限を待つうちに期限を超過しました。リクエストは Langfuse に送信されていません	一度に行う呼び出しを減らすか、Langfuse のプランで許可されている場合は LANGFUSE_MCP_RATE_LIMIT／LANGFUSE_MCP_MAX_CONCURRENCY を引き上げてください
ツールエラー timeout、retryable: false	Langfuse が 60 秒のリクエスト期限内に応答しませんでした	操作で指定できる条件を使ってクエリの範囲を狭めてください。fields のフィールドグループを減らす、limit を下げる、または時間範囲を短くします（ヒントには、その操作で指定できる条件のみが示されます）。Langfuse 3.80.0 の trace_get や legacy_observationsV1_get のように、これらの条件が使えない操作は、このサーバー経由で負荷を下げることができません。ヒントに従ってユーザーに伝えてください
エージェントがデータを変更できないと伝え、ツール一覧に execute_write がない	書き込みモードがオフ（デフォルト）です。execute_write は登録されず、検出ツールでは書き込み操作が非表示になります	LANGFUSE_MCP_ALLOW_WRITES=true（環境変数または設定ファイル）を設定して、サーバーを再起動してください。ツールセットは起動時に固定されます
削除または更新が confirmation_unavailable で失敗する	クライアントがフォームを表示できない（MCP フォームの引き出しに未対応）ため、サーバーが破壊的な呼び出しの確認を求められません。何も送信されていません	フォームの引き出しに対応したクライアントを使用してください。確認を省略する設定はありません
削除または更新が confirmation_declined で失敗し、フォームも表示されなかった	クライアントがサーバーのフォームに自動で応答しました。2026-10-11、Claude デスクトップアプリの Code タブ（2.1.295）で発生が確認されています（Claude Code ターミナル CLI（2.1.296）ではフォームが表示されました）。何も送信されていません	Claude Code ターミナル CLI など、フォームを表示するクライアントから呼び出すか、Langfuse UI で変更してください

詳しくはこちら

• ドキュメント索引：ツール、設定、インストールとセキュリティ、およびサーバーの構築方法に関するリファレンスです。
• コントリビューション：ビルド、テスト、およびプルリクエストで合格が必要なチェックについて説明しています。

参考資料

• Langfuse のドキュメント：https://langfuse.com/docs
• API リファレンス：https://api.reference.langfuse.com
• データリージョン：https://langfuse.com/security/data-regions
• MCP 仕様：https://modelcontextprotocol.io
• Go SDK：https://github.com/modelcontextprotocol/go-sdk
• OWASP GenAI Security Project：https://genai.owasp.org
• OWASP MCP Top 10：https://github.com/OWASP/www-project-mcp-top-10
• Node.js のエンタープライズネットワーク設定（Node ベースのツールが企業の CA で失敗する理由）：https://nodejs.org/learn/http/enterprise-network-configuration

ライセンス

Apache-2.0。商用利用は無料で、明示的な特許ライセンスが付与されています。