--- title: MCP Server sidebarTitle: MCP Server description: Native Model Context Protocol (MCP) server for Langfuse, enabling AI assistants to interact with your Langfuse data programmatically. --- # Langfuse MCP Server Langfuse includes a native [Model Context Protocol](https://modelcontextprotocol.io) (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](https://github.com/orgs/langfuse/discussions/10605). 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](/docs/api-and-data-platform/features/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](/docs/docs-mcp)). ## MCP Reference The [MCP Reference](https://mcp.reference.langfuse.com) 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](https://mcp.reference.langfuse.com). ## Set up [#set-up] 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. ### 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: ```bash filename="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: ```bash filename="terminal" /{your-base64-token}/ # 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: ```toml filename="~/.codex/config.toml" /{your-base64-token}/ [mcp_servers.langfuse] url = "https://cloud.langfuse.com/api/public/mcp" http_headers = { "Authorization" = "Basic {your-base64-token}" } ``` ```toml filename="~/.codex/config.toml" /{your-base64-token}/ [mcp_servers.langfuse] url = "https://us.cloud.langfuse.com/api/public/mcp" http_headers = { "Authorization" = "Basic {your-base64-token}" } ``` ```toml filename="~/.codex/config.toml" /{your-base64-token}/ [mcp_servers.langfuse] url = "https://jp.cloud.langfuse.com/api/public/mcp" http_headers = { "Authorization" = "Basic {your-base64-token}" } ``` ```toml filename="~/.codex/config.toml" /{your-base64-token}/ [mcp_servers.langfuse] url = "https://hipaa.cloud.langfuse.com/api/public/mcp" http_headers = { "Authorization" = "Basic {your-base64-token}" } ``` ```toml filename="~/.codex/config.toml" /{your-base64-token}/ [mcp_servers.langfuse] url = "https://your-domain.com/api/public/mcp" http_headers = { "Authorization" = "Basic {your-base64-token}" } ``` 2. Restart Codex and run `codex mcp list` to confirm the server is registered. 3. 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: ```json filename="mcp.json" /{your-base64-token}/ { "mcp": { "servers": { "langfuse": { "url": "https://cloud.langfuse.com/api/public/mcp", "headers": { "Authorization": "Basic {your-base64-token}" } } } } } ``` ```json filename="mcp.json" /{your-base64-token}/ { "mcp": { "servers": { "langfuse": { "url": "https://us.cloud.langfuse.com/api/public/mcp", "headers": { "Authorization": "Basic {your-base64-token}" } } } } } ``` ```json filename="mcp.json" /{your-base64-token}/ { "mcp": { "servers": { "langfuse": { "url": "https://jp.cloud.langfuse.com/api/public/mcp", "headers": { "Authorization": "Basic {your-base64-token}" } } } } } ``` ```json filename="mcp.json" /{your-base64-token}/ { "mcp": { "servers": { "langfuse": { "url": "https://hipaa.cloud.langfuse.com/api/public/mcp", "headers": { "Authorization": "Basic {your-base64-token}" } } } } } ``` ```json filename="mcp.json" /{your-base64-token}/ { "mcp": { "servers": { "langfuse": { "url": "https://your-domain.com/api/public/mcp", "headers": { "Authorization": "Basic {your-base64-token}" } } } } } ``` 5. Save the file and restart Cursor 6. The server should appear in the MCP settings with a green dot indicating it's active [Pi](https://pi.dev) does not ship with built-in MCP support. Use the community-maintained [`pi-mcp-adapter`](https://github.com/nicobailon/pi-mcp-adapter) extension, which exposes MCP servers to Pi through a single proxy tool. 1. Install the extension and restart Pi: ```bash 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: ```json filename="~/.pi/agent/mcp.json" /{your-base64-token}/ { "mcpServers": { "langfuse": { "url": "https://cloud.langfuse.com/api/public/mcp", "headers": { "Authorization": "Basic {your-base64-token}" } } } } ``` ```json filename="~/.pi/agent/mcp.json" /{your-base64-token}/ { "mcpServers": { "langfuse": { "url": "https://us.cloud.langfuse.com/api/public/mcp", "headers": { "Authorization": "Basic {your-base64-token}" } } } } ``` ```json filename="~/.pi/agent/mcp.json" /{your-base64-token}/ { "mcpServers": { "langfuse": { "url": "https://jp.cloud.langfuse.com/api/public/mcp", "headers": { "Authorization": "Basic {your-base64-token}" } } } } ``` ```json filename="~/.pi/agent/mcp.json" /{your-base64-token}/ { "mcpServers": { "langfuse": { "url": "https://hipaa.cloud.langfuse.com/api/public/mcp", "headers": { "Authorization": "Basic {your-base64-token}" } } } } ``` ```json filename="~/.pi/agent/mcp.json" /{your-base64-token}/ { "mcpServers": { "langfuse": { "url": "https://your-domain.com/api/public/mcp", "headers": { "Authorization": "Basic {your-base64-token}" } } } } ``` 3. 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. - Transport: `streamableHttp` - Authentication: Basic Auth via authorization header - `Authorization: Basic {your-base64-token}` ## Filter logical root observations [#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](https://mcp.reference.langfuse.com). ## 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](https://github.com/orgs/langfuse/discussions/10605). ## Related Documentation - [MCP Reference](https://mcp.reference.langfuse.com) - Reference for MCP servers, setup snippets, tools, schemas, and requests - [Agentic Prompt Management](/docs/prompt-management/features/agentic-access) - Use agents to retrieve, create, migrate, and update prompts - [Prompt Management Overview](/docs/prompt-management/overview) - Learn about Langfuse prompt management - [Public API](/docs/api-and-data-platform/features/public-api) - REST API for programmatic access - [Langfuse Agent Skill](/docs/api-and-data-platform/features/agent-skill) - Use Langfuse features from your coding agent - [Langfuse for Agents](/agents) - Overview of the skill, CLI, and MCP server for coding agents --- ## Agent Instructions This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/docs/api-and-data-platform/features/mcp-server.md`. ### Querying these docs If the answer is not on this page, query the documentation instead of guessing: - **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question: ```bash curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?" ``` - **Index of every page**: , with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt). ### Before writing Langfuse code - **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results. - **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application. - **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples. - **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api `) to read or write traces, prompts, datasets, and scores from the terminal. Found an error in these docs? Please open an issue at .