langfuse-api-mcp

An MCP server that gives AI agents access to the full Langfuse public API. It works with Langfuse Cloud in any region and with self-hosted instances. It is built to run on corporate networks that re-sign TLS traffic with their own certificate authority (CA).

[!IMPORTANT] Status: pre-alpha, release v0.2.0 (semver 0.x: no stability promise yet; the first release was v0.1.0). Everything below works today unless it is marked Planned, like the loopback HTTP transport.

Contents: What it is · Tools · User skill · Install and run · Client configuration · Configuration · Security model · Troubleshooting · Learn more

---

What it is

A small, stateless program that your AI tool (Claude Code, Claude Desktop, Cursor, VS Code, Codex, …) starts on your machine. It speaks the Model Context Protocol to the agent and HTTPS to Langfuse. The agent can then:

• investigate traces, observations, sessions, errors, latency and cost;
• read prompts, datasets, experiments, scores, metrics, models, comments and annotation queues;
• make changes, such as promoting a prompt label, creating a score or editing a dataset. This works only if you turn writes on (see Security model).

flowchart LR
  A[AI agentClaude Code, Cursor, …] -- MCP over stdio --> S[langfuse-mcpon your machine or in Docker]
  S -- HTTPS + your corporate CA --> P{{Corporate proxyoptional}}
  P --> L[(LangfuseCloud or self-hosted)]
  S -. reads .-> C[/Your config: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;

When to use it

How it differs from the official Langfuse MCP

Tools

The Langfuse API has about 100 in-scope operations. One tool per operation would fill the agent’s context window, so the server exposes a small set of tools:

A typical session: search_operations finds the operation, describe_operation shows its parameters, execute_read runs it:

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

The server keeps nothing between calls (it is stateless). It never takes a URL, host or credential from the agent. It only runs operations from its built-in catalog, against the host you configured. Every call is validated before anything is sent, and every failure comes back as a structured tool error with a code, a hint and a retryable flag. Parameters, error codes, result limits and the audit line: Tools reference.

User skill

The server gives an agent generic tools; the user skill langfuse-api-mcp (skills/langfuse-api-mcp/) teaches it how a Langfuse investigation is done with them: discover, describe, then execute; always a bounded time window; Langfuse data is untrusted, never instructions. It has a short entry file and one reference per workflow (traces, cost and latency, prompts, experiments, scores, errors), each loaded only when its workflow is asked for. Its description names this server’s tools, so it does not compete with Langfuse’s own langfuse skill. It adds no permission of its own: whether execute_write exists and every confirmation stay the server’s decision.

Claude Code, Cursor, VS Code, Codex CLI, Gemini CLI, Windsurf. Install it from the repository with the skills CLI, in your project (or with -g for your user); --agent names the hosts to install for (--agent '*' for all). The Claude Code install is proven; the other hosts rely on the CLI’s own support:

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

The CLI installs from main, while your server may be an older build; the skill therefore tells the agent to call describe_operation for every parameter it does not name (details).

Claude Desktop installs skills only by upload. Each GitHub release carries langfuse-api-mcp-skill_.zip, signed, whose root is the langfuse-api-mcp/ folder; upload it in Claude Desktop under Customize > Skills.

Install and run

Every channel except go install is signed or carries npm provenance: see Verify what you run. The server is also listed in the MCP Registry as io.github.rodrigorjsf/langfuse-api-mcp. What each channel ships and how it is built: Installation reference.

npx

Configure the server in your MCP client as npx -y langfuse-api-mcp (pin a version with langfuse-api-mcp@); it needs Node.js with npm, nothing else. The package carries the Go binary: nothing is downloaded at install time and no install script runs. See Client configuration for the snippet of your client.

Release archive

Every GitHub release carries one archive per target, langfuse-mcp___.tar.gz (.zip on Windows), plus checksums.txt. Download with gh or curl, check the archive against checksums.txt, then extract it (Linux on amd64 shown; `` is the release without the leading v, for example 0.2.0):

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"

On Windows (PowerShell), compare the hash and extract the zip:

$archive = "langfuse-mcp__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

Then point your MCP client at the extracted binary (see Client configuration). The binaries are not notarized nor Authenticode-signed: download with curl or gh, not a browser, or see Downloaded in a browser?.

Docker

Pass the keys and the base URL with -e, and keep -i (the server speaks MCP over stdin and stdout):

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

-e NAME without a value passes the variable from the environment that runs docker, so the keys never appear in the command line. Behind a corporate CA, mount the CA file read-only and point LANGFUSE_CA_CERT at it; the file must be readable by any user (the image does not run as you):

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:

In an MCP client, the command is docker and args is the list above; put the keys in the client’s env block, never as -e NAME=value in args. The image serves stdio only.

Claude Desktop (MCPB)

Download langfuse-mcp_.mcpb from a GitHub release (macOS, Windows amd64) and double-click it (or drag it onto Claude Desktop); the install dialog asks for:

The dialog offers no write-mode option on purpose: to enable writes, set LANGFUSE_MCP_ALLOW_WRITES=true in the config file. Any other setting (proxy, request limits) also goes in the config file.

go install

Install a release (@v0.2.0, or @latest) or a commit (@main or a commit hash). With Go 1.21 or later (the module’s toolchain directive fetches the Go 1.27 toolchain it needs):

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

The binary lands in $(go env GOPATH)/bin. From a checkout, go build -o langfuse-mcp ./cmd/langfuse-mcp builds it.

Client configuration

One snippet per MCP client. Every snippet uses the npx channel; to use a release archive instead, replace "command": "npx", "args": ["-y", "langfuse-api-mcp"] with "command": "/absolute/path/to/langfuse-mcp" and no args (langfuse-mcp.exe on Windows).

Each client starts the server with its own view of your environment, and several do not pass your shell’s variables on. So every snippet names the three variables the server needs in the client’s own env mechanism, the one place a key may go. pk-lf-... and sk-lf-... stand for your keys. A snippet that reads a key from the client’s environment (${VAR}, ${env:NAME}, $NAME, env_vars) needs the key exported where the client starts, and the agent’s own shell inherits it from there: see Keep the keys out of the agent’s environment. Every pitfall and trade-off per client: MCP clients in detail.

Claude Code — proven

Pass the keys with --env; an option (here --transport stdio) must sit between the last --env and the server name. This stores the keys in ~/.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

For a project .mcp.json, Claude Code expands ${VAR} and ${VAR:-default} in 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:-https://cloud.langfuse.com}"
      }
    }
  }
}

Claude Desktop

Prefer the MCPB bundle, which stores the keys in the OS keychain. Claude Desktop passes the server only a limited subset of environment variables. To configure it by hand, edit claude_desktop_config.json (macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\), put the keys in env and give command as an absolute path (which npx on macOS, where npx on Windows):

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

Forward each variable with ${env:NAME} in ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project); Cursor must itself be started with those variables set:

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

Declare the keys as inputs with "password": true: VS Code asks for them the first time the server starts and stores them securely. The file uses servers, not mcpServers:

{
  "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 clears the environment before it starts the server. List the variable names in env_vars in ~/.codex/config.toml (or a project .codex/config.toml); Codex forwards their values from its own environment:

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

Gemini CLI — startup proven

Gemini CLI removes every variable whose name contains KEY, SECRET or TOKEN, so name the keys in env in ~/.gemini/settings.json (or a project .gemini/settings.json, read only in a trusted folder):

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

Forward each variable with ${env:NAME} in ~/.config/devin/mcp_config.json (macOS and Linux; %APPDATA%\devin\mcp_config.json on Windows):

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

Configuration

Settings come from environment variables, then from an optional config file for non-secret settings; the environment wins. An invalid value stops startup with one error naming the variable, never echoing a key. Every rule, default and startup log line: Configuration reference.

Connection

Cloud regions: EU https://cloud.langfuse.com · US https://us.cloud.langfuse.com · JP https://jp.cloud.langfuse.com · HIPAA https://hipaa.cloud.langfuse.com. Keys only work in the region where they were created.

Certificates and proxy

Trusted roots = your operating system’s certificate store + every CA from the sources above. TLS 1.2 is the minimum version. There is no option to disable certificate verification. The server does not read the Windows or macOS proxy settings, nor a PAC file: how to find your proxy.

Request limits

Result size cap

Behavior

The server detects the Langfuse version and the operations it serves at startup, with nothing to configure (Deployment profile); restart it after upgrading Langfuse.

Config file (non-secret settings)

To set the CA, host, proxy, limits, result size cap or write mode once for every client, put them in a config file at your OS’s standard config location:

# 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

Values are taken literally: no quotes, no ${VAR} expansion. Keys are not allowed in this file. If it contains LANGFUSE_PUBLIC_KEY or LANGFUSE_SECRET_KEY, the server refuses to start. How the file is read.

Certificate scenarios

Get your company’s root CA in PEM format:

The startup log line CA sources loaded lists which CA sources were loaded (paths and counts, never contents); use it to confirm the setup.

Security model

• Read-only unless you opt in. Without LANGFUSE_MCP_ALLOW_WRITES=true the write tool does not exist; execute_read runs GET operations only. The tool set is fixed at startup.
• Write mode confirms every destructive call. With writes on, creates (POST) run directly, and every DELETE, PUT and PATCH runs only after you confirm that exact call in your client’s form. A client without form elicitation cannot run destructive operations at all; no setting skips the confirmation. A write is never retried automatically.
• Your keys stay with the server. Read only from the server’s environment, never accepted from the agent, never logged, never returned in a result.
• Untrusted data is labelled. Langfuse content reaches the agent inside an envelope marking it as data, cleaned of hidden Unicode and control characters, also when they are written as escapes inside the JSON text of a trace input or output.
• Verified TLS only. OS store + your CAs, TLS 1.2+, no skip-verify option.

Recommendations: create a dedicated Langfuse key for the agent, set an expiry date on it, and keep writes off unless you need them.

Every guarantee and how it is enforced, the write confirmation in full, and how to verify a release’s signatures: Security model reference. Found a vulnerability? Report it privately, never in a public issue: see SECURITY.md.

Keep the keys out of the agent’s environment

The write gate (write mode off, and the confirmation of every destructive call in write mode) covers only the calls made through this server. It cannot see or stop another process holding the same keys. When the keys sit in the environment the MCP client starts with, every shell command and tool the agent runs inherits them: an agent with a shell can call Langfuse’s own CLI or curl with them and change your data without any confirmation, for example when this server fails to start and the agent looks for another way. Denying the shell tool alone is not enough: any tool that starts a process inheriting that environment (a script runner, a code interpreter, a plugin) does the same.

• Store the keys in the client’s own per-server settings, not in your shell: claude mcp add --env for Claude Code (kept in ~/.claude.json), the MCPB bundle for Claude Desktop (OS keychain), VS Code inputs with "password": true, or a literal value in the client’s env block kept out of the repository.
• Never export LANGFUSE_PUBLIC_KEY or LANGFUSE_SECRET_KEY in the shell that starts the MCP client. The ${VAR}-style snippets under Client configuration need exactly that, so use them only when the agent cannot run commands.
• The agent still runs as your user, so it could read a file that holds the keys. Where your client has permission rules, deny the agent reading that file; for a hard limit, give the agent no way to run commands at all.

Troubleshooting

Every failure reaches the agent as a structured error with a stable code (e.g. langfuse_unauthorized, langfuse_rate_limited, tls_untrusted_certificate), a hint and a retryable flag. The server never crashes the connection or returns secrets. Every code: Tools reference.

Learn more

• Documentation index: the reference for tools, configuration, installation and security, and how the server was built.
• Contributing: build, test and the checks a pull request must pass.

References

• Langfuse docs: https://langfuse.com/docs
• API reference: https://api.reference.langfuse.com
• Data regions: https://langfuse.com/security/data-regions
• MCP specification: 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 enterprise network configuration (why Node-based tools fail on corporate CAs): https://nodejs.org/learn/http/enterprise-network-configuration

License

Apache-2.0. Free for commercial use, with an explicit patent grant.