Langfuse MCP Server#

Langfuse ships a native Model Context Protocol (MCP) server at the endpoint /api/public/mcp. It lets AI assistants and agents (Claude Code, Cursor, Claude Desktop, etc.) interact with Langfuse project data — prompts, observations, traces, scores, datasets, and more — without leaving their context. 1

When to use MCP vs. CLI: The MCP server is best for environments that cannot install or run CLI tools (Claude Desktop, Linear Agents, etc.). If your agent runs in a sandbox with shell access, the Langfuse CLI is the preferred approach because it lets agents pre-filter data and avoids flooding the context window with large payloads. 2

Endpoint and Transport#

Transport: streamableHttp (MCP 2025-03-26 spec, single endpoint for POST/GET/DELETE). This is not the deprecated HTTP+SSE transport. The implementation is stateless per-request — a fresh server instance is created per request with no session storage.

Authentication#

Authentication uses Basic Auth with project-scoped API keys only. Bearer tokens and org-level keys are explicitly rejected 3.

1. From project settings, copy your Public Key (pk-lf-...) and Secret Key (sk-lf-...).

2. Base64-encode pk-lf-...:sk-lf-...:

   ⧉

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

3. Pass as Authorization: Basic {your-base64-token}.

Each API key is scoped to a single project — multi-project access in a single session is not currently supported. 2

Available Tools#

The full tool list lives at mcp.reference.langfuse.com. Both read and write tools are enabled by default. Restrict to read-only by configuring an allowlist in your MCP client. 1

Key tool categories (as of the May 2026 update) 4:

• Prompts: getPrompt, getPromptUnresolved, listPrompts, createTextPrompt, createChatPrompt, updatePromptLabels
• Observations, Metrics, Scores, Score configs
• Comments, Datasets, Dataset items/runs/run items
• Models, Annotation queues/items/assignments
• Media, Health

Note: The Metrics and Observations tools require the v4 data model, which is not yet available in the self-hosted version as of mid-2026. 2

Version Requirements (Self-Hosted)#

The MCP endpoint was introduced in v3.133.0 5. Most MCP tools were added in v3.177.0 2. No feature flag is required; the endpoint is active out-of-the-box once you upgrade.

To upgrade on Kubernetes, update your values.yaml to reference langfuse/langfuse:3.177.0 or newer and run helm upgrade. See langfuse-k8s releases for chart versions that bundle an appropriate appVersion.

Reverse Proxy and Networking (Self-Hosted)#

The server validates the Host header against the hostname extracted from NEXTAUTH_URL 6. A mismatch causes a 403 Forbidden.

Key considerations for nginx/ingress:

• The Host header forwarded to the app must match the hostname in NEXTAUTH_URL. If your proxy rewrites it to an internal address, the request will be rejected 7.
• The documentation refers to LANGFUSE_MCP_ALLOWED_HOSTS, but the actual implementation uses NEXTAUTH_URL as the allowed hostname source — there is no separate LANGFUSE_MCP_ALLOWED_HOSTS env var in the current codebase. 8
• Disable response buffering (proxy_buffering off / X-Accel-Buffering: no) — the server sets this header itself, but make sure your proxy does not override it. 5
• Increase proxy_read_timeout and proxy_send_timeout for long-lived SSE connections. 5
• HTTPS is required for all non-localhost deployments. 1
• CORS is handled internally by the server; no special ingress CORS config is needed. 5

Cursor IDE Setup#

1. Open Cursor Settings (Cmd/Ctrl + Shift + J) → Tools & Integrations → Add Custom MCP.
2. Add the following configuration (replace {your-base64-token}):

{
  "mcp": {
    "servers": {
      "langfuse": {
        "url": "https://cloud.langfuse.com/api/public/mcp",
        "headers": {
          "Authorization": "Basic {your-base64-token}"
        }
      }
    }
  }
}

3. Save and restart Cursor. A green dot in MCP settings confirms a successful connection. 1

For self-hosted, replace the URL with https://your-domain.com/api/public/mcp.

Key Source Files#

Related Resources#

• Official MCP docs
• MCP Reference (full tool list)
• May 2026 MCP changelog 4
• Prompt Management MCP
• Langfuse CLI — recommended alternative for CLI agents