Langfuse details how it built Halo, its in-product agent, on its own MCP server

An agent assembled from existing parts

Halo lets users ask for help interpreting traces, building a dashboard or dataset, or setting up evals without leaving the Langfuse UI. Author Lotte Ben admits the irony that Langfuse, a company focused on helping others build agents, had no in-product agent of its own. Users were already working with the Langfuse skill, MCP server and CLI through their own agents, and the team wanted those capabilities inside the product.

The first version, Ben writes, was simply a Mastra agent, an MCP server and glue code. The team did not invent a new execution algorithm and did not rewrite anything in Rust. The goal was to reuse as much as possible so that Langfuse would not have to maintain a second set of tools and instructions just for Halo. A fix to a tool or a piece of guidance then benefits both the in-product agent and power users with their own setups.

From MCP expansion to background runs

The first step was expanding the MCP server. According to Langfuse, the May 29 release added tools for observations, metrics, scores, comments, datasets and annotation queues, which made most project data available to agents.

• June 19: Langfuse Assistant public beta, a Mastra agent behind an HTTP endpoint that streamed responses to the browser and handled one conversation at a time
• July 1: write actions with human-in-the-loop approvals
• August 6: background execution
• August 13: sandbox-enabled runs

The company announced these capabilities together in September. In the final architecture, the browser starts a run and the web service saves it to Postgres. A run ID is queued in BullMQ, and a worker picks it up and executes the agent loop, calling Claude on Bedrock and the Langfuse MCP server. Because the worker is independent of the browser, users can close the tab and return later. The saved event log lets the UI catch up.

Permissions enforced through tools

Halo reaches project data only through the public MCP server. It also gets sandbox tools similar to those in coding agents and UI-specific tools, such as proposing navigation to another page. The system prompt includes the user's name, time zone, browser languages and current URL.

For each run, the worker creates a temporary API key scoped to the project, which by default can only call read-only MCP tools. Langfuse keeps its own mapping of tool permissions in the agent's code instead of trusting the MCP server's read-only annotations. Tools are also filtered by the signed-in user's role, so a tool the user may not use is never exposed to the model.

Tools that change data require approval. Choosing Always approve saves the approval for that conversation only, and it is rechecked against the user's current role on each run. If Halo needs a new way to access data, the team must first add an MCP tool, a constraint Ben says he likes because the same tool then reaches people using their own agents. For guidance such as setting up evals or migrating prompts, Halo loads the open-source Langfuse skill as a Mastra skill and relies on the Docs MCP.

Dogfooding with Langfuse traces

Langfuse uses its own product to analyze Halo. When an organization opts into AI feature telemetry, the team can use traces of Halo runs to see where the agent struggles, then fix the MCP tool, shared skill or documentation.

Ben gives several examples. Agents kept sorting metrics by totalCost_sum when the tool expected sum_totalCost, so the MCP adapter now accepts both. Dashboard validation errors named the wrong field but not the alternatives, so the team added allowed values and guidance on looking up the schema. When Halo became expensive to run, traces showed that prompt caching was not working as expected. Fixing it cut costs enough to make running Halo with more capable models viable again.

Ben also notes that people have tried to break or exploit Halo since the announcement, and such attempts still turn up regularly. Those attempts reinforce the strict boundaries around what the agent can access.

Why the agent stays outside the sandbox

When the sandbox arrived, Langfuse kept the agent loop in its backend workers. The agent gets four tools, read, write, edit and bash, to work with files and run scripts in a separate environment. A sandbox is created when the agent first uses one of them in a conversation. It has no network access by default, code runs as an unprivileged user, and an idle sandbox is suspended and eventually terminated and cleaned up.

No process inside can contact Langfuse or the wider internet directly. The agent can only push data in after fetching it through authorized MCP calls, so the team did not need to defend against arbitrary network calls from within the sandbox. Many conversations, such as a docs question or a lookup of yesterday's traces, need no sandbox, and starting a VM for them would waste memory and disk.

For Langfuse Cloud, the sandbox runs on AWS Lambda MicroVMs, but the interface is built to be adaptable to other providers. Self-hosters can choose not to use a sandbox at all.

What it means for users

For Langfuse users, the design means improvements made for Halo carry over to the MCP server, skill and docs they use with agents such as Claude Code or Cursor. Self-hosting teams keep the option to run the assistant without a sandbox.