Langfuse v4: up to 165× faster · Read more
DocsMCP Server
DocsAPI & Data PlatformFeaturesMCP Server

Langfuse MCP Server

Langfuse includes a native Model Context Protocol (MCP) server that enables AI assistants and agents to interact with your Langfuse data programmatically.

If you have feedback or ideas for new tools, please share them on GitHub.

If you are running AI agents in an environment where you can install CLI tools and run bash commands, we recommend using the Langfuse Agent Skill instead of the MCP server.

This is the authenticated MCP server for the Langfuse data platform. There is also a public MCP server for the Langfuse documentation (docs).

Configuration

The Langfuse MCP server uses a stateless architecture where each API key is scoped to a specific project. Use the following configuration to connect to the MCP server:

  • Endpoint: https://cloud.langfuse.com/api/public/mcp
  • Transport: streamableHttp
  • Authentication: Basic Auth via authorization header
  • Endpoint: https://us.cloud.langfuse.com/api/public/mcp
  • Transport: streamableHttp
  • Authentication: Basic Auth via authorization header
  • Endpoint: https://jp.cloud.langfuse.com/api/public/mcp
  • Transport: streamableHttp
  • Authentication: Basic Auth via authorization header
  • Endpoint: https://hipaa.cloud.langfuse.com/api/public/mcp
  • Transport: streamableHttp
  • Authentication: Basic Auth via authorization header
  • Endpoint: https://your-domain.com/api/public/mcp
  • Transport: streamableHttp
  • Authentication: Basic Auth via authorization header
  • For reverse-proxy deployments, make sure the proxy preserves the public Host header. If the MCP endpoint receives an internal host instead, set LANGFUSE_MCP_ALLOWED_HOSTS to a comma-separated list of exact additional hostnames or origins accepted by the MCP endpoint. Otherwise, you get a 403 error.

MCP Reference

The MCP Reference is the canonical source for current Langfuse MCP servers, setup snippets, tools, input schemas, and generated request examples.

Both read and write tools are available by default. If you only want to use read-only tools, configure your MCP client with an allowlist to restrict access to write operations. For a full list of tools, see the MCP Reference.

Filter logical root observations

The observation tools distinguish logical roots from physical parentage:

  • listObservations accepts the optional boolean isRootObservation filter. Set it to true to match observations without a physical parent or observations explicitly marked as application roots by the SDK.
  • Physical-parent filtering remains separate. An application-root observation can match isRootObservation: true even when it has a physical parent.
  • isRootObservation is included in the default observation fields returned by listObservations.
  • getObservationFilterValues supports isRootObservation as a filter-value column, so you can discover and combine logical-root values with other observation filters.

For the complete tool schemas and request examples, see the MCP Reference.

Set up

Get Authentication Header

  1. Navigate to your project settings and create or copy a project-scoped API key:
    • Public Key: pk-lf-...
    • Secret Key: sk-lf-...
  2. Encode the credentials to base64 format:
    your-base64-token
    echo -n "pk-lf-your-public-key:sk-lf-your-secret-key" | base64

Client Setup

  1. Register the Langfuse MCP server with a single command, replace {your-base64-token} with your encoded credentials:

    terminal
    # Langfuse Cloud (EU)
claude mcp add --transport http langfuse https://cloud.langfuse.com/api/public/mcp \
    --header "Authorization: Basic {your-base64-token}"

# Langfuse Cloud (US)
claude mcp add --transport http langfuse https://us.cloud.langfuse.com/api/public/mcp \
    --header "Authorization: Basic {your-base64-token}"

# Langfuse Cloud (Japan)
claude mcp add --transport http langfuse https://jp.cloud.langfuse.com/api/public/mcp \
    --header "Authorization: Basic {your-base64-token}"

# Langfuse Cloud (HIPAA)
claude mcp add --transport http langfuse https://hipaa.cloud.langfuse.com/api/public/mcp \
    --header "Authorization: Basic {your-base64-token}"

# Self-Hosted (HTTPS required)
claude mcp add --transport http langfuse https://your-domain.com/api/public/mcp \
    --header "Authorization: Basic {your-base64-token}"

# Local Development
claude mcp add --transport http langfuse http://localhost:3000/api/public/mcp \
    --header "Authorization: Basic {your-base64-token}"

  2. Verify the connection by asking Claude Code to list all prompts in the project. Claude Code should use the listPrompts tool to return the list of prompts.

  1. Add the Langfuse MCP server to ~/.codex/config.toml, replace {your-base64-token} with your encoded credentials:
~/.codex/config.toml
[mcp_servers.langfuse]
url = "https://cloud.langfuse.com/api/public/mcp"
http_headers = { "Authorization" = "Basic {your-base64-token}" }
~/.codex/config.toml
[mcp_servers.langfuse]
url = "https://us.cloud.langfuse.com/api/public/mcp"
http_headers = { "Authorization" = "Basic {your-base64-token}" }
~/.codex/config.toml
[mcp_servers.langfuse]
url = "https://jp.cloud.langfuse.com/api/public/mcp"
http_headers = { "Authorization" = "Basic {your-base64-token}" }
~/.codex/config.toml
[mcp_servers.langfuse]
url = "https://hipaa.cloud.langfuse.com/api/public/mcp"
http_headers = { "Authorization" = "Basic {your-base64-token}" }
~/.codex/config.toml
[mcp_servers.langfuse]
url = "https://your-domain.com/api/public/mcp"
http_headers = { "Authorization" = "Basic {your-base64-token}" }
  1. Restart Codex and run codex mcp list to confirm the server is registered.
  2. Verify the connection by asking Codex to list all prompts in the project. Codex should use the listPrompts tool to return the list of prompts.
  1. Open Cursor Settings (Cmd/Ctrl + Shift + J)
  2. Navigate to Tools & Integrations tab
  3. Click "Add Custom MCP"
  4. Add your Langfuse MCP server configuration, replace {your-base64-token} with your encoded credentials:
mcp.json
{
  "mcp": {
    "servers": {
      "langfuse": {
        "url": "https://cloud.langfuse.com/api/public/mcp",
        "headers": {
          "Authorization": "Basic {your-base64-token}"
        }
      }
    }
  }
}
mcp.json
{
  "mcp": {
    "servers": {
      "langfuse": {
        "url": "https://us.cloud.langfuse.com/api/public/mcp",
        "headers": {
          "Authorization": "Basic {your-base64-token}"
        }
      }
    }
  }
}
mcp.json
{
  "mcp": {
    "servers": {
      "langfuse": {
        "url": "https://jp.cloud.langfuse.com/api/public/mcp",
        "headers": {
          "Authorization": "Basic {your-base64-token}"
        }
      }
    }
  }
}
mcp.json
{
  "mcp": {
    "servers": {
      "langfuse": {
        "url": "https://hipaa.cloud.langfuse.com/api/public/mcp",
        "headers": {
          "Authorization": "Basic {your-base64-token}"
        }
      }
    }
  }
}
mcp.json
{
  "mcp": {
    "servers": {
      "langfuse": {
        "url": "https://your-domain.com/api/public/mcp",
        "headers": {
          "Authorization": "Basic {your-base64-token}"
        }
      }
    }
  }
}
  1. Save the file and restart Cursor
  2. The server should appear in the MCP settings with a green dot indicating it's active

Pi does not ship with built-in MCP support. Use the community-maintained pi-mcp-adapter extension, which exposes MCP servers to Pi through a single proxy tool.

  1. Install the extension and restart Pi:

    pi install npm:pi-mcp-adapter

  2. Add the Langfuse MCP server to ~/.pi/agent/mcp.json, replace {your-base64-token} with your encoded credentials:

~/.pi/agent/mcp.json
{
  "mcpServers": {
    "langfuse": {
      "url": "https://cloud.langfuse.com/api/public/mcp",
      "headers": {
        "Authorization": "Basic {your-base64-token}"
      }
    }
  }
}
~/.pi/agent/mcp.json
{
  "mcpServers": {
    "langfuse": {
      "url": "https://us.cloud.langfuse.com/api/public/mcp",
      "headers": {
        "Authorization": "Basic {your-base64-token}"
      }
    }
  }
}
~/.pi/agent/mcp.json
{
  "mcpServers": {
    "langfuse": {
      "url": "https://jp.cloud.langfuse.com/api/public/mcp",
      "headers": {
        "Authorization": "Basic {your-base64-token}"
      }
    }
  }
}
~/.pi/agent/mcp.json
{
  "mcpServers": {
    "langfuse": {
      "url": "https://hipaa.cloud.langfuse.com/api/public/mcp",
      "headers": {
        "Authorization": "Basic {your-base64-token}"
      }
    }
  }
}
~/.pi/agent/mcp.json
{
  "mcpServers": {
    "langfuse": {
      "url": "https://your-domain.com/api/public/mcp",
      "headers": {
        "Authorization": "Basic {your-base64-token}"
      }
    }
  }
}
  1. Restart Pi and verify the connection by asking Pi to list all prompts in the project. Pi should use the listPrompts tool via the MCP proxy to return the list of prompts.
  • Endpoint: /api/public/mcp
    • EU: https://cloud.langfuse.com/api/public/mcp
    • US: https://us.cloud.langfuse.com/api/public/mcp
    • Japan: https://jp.cloud.langfuse.com/api/public/mcp
    • HIPAA: https://hipaa.cloud.langfuse.com/api/public/mcp
    • Self-Hosted: https://your-domain.com/api/public/mcp
  • Transport: streamableHttp
  • Authentication: Basic Auth via authorization header
    • Authorization: Basic {your-base64-token}

Feedback

We'd love to hear about your experience with the Langfuse MCP server. Share your feedback, ideas, and use cases in our GitHub Discussion.

Was this page helpful?

Last edited

PreviousCLI
NextExport from UI

On this page

Langfuse MCP ServerConfigurationMCP ReferenceFilter logical root observationsSet upGet Authentication HeaderClient SetupFeedbackRelated Documentation

Actions

Give us feedbackEdit this page on GitHub

Contributors

Last edited

Valeriy MeleshkinValeriy MeleshkinLotte VerheydenLotte VerheydenJannik MaierhöferJannik Maierhöfer
GitHub