Langfuse API

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 agent Claude Code, Cursor, …] -- MCP over stdio --> S[langfuse-mcp on your machine or in Docker] S -- HTTPS + your corporate CA --> P{{Corporate proxy optional}} P --> L[(Langfuse Cloud 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=<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_<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

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 L