Skip to content

Flue

Connect Flue agents to xmcp tools over Streamable HTTP, and call a deployed Flue agent from an xmcp tool.

For the complete documentation index, see llms.txt. Markdown variants of every page are available by appending .md to the URL.

Flue agents can consume xmcp tools through Flue's native MCP connections, and an xmcp tool can call a deployed Flue agent. The runnable example does both with one read-only tool and one agent.

Shell

Give a Flue agent xmcp tools

Protect the xmcp server with a bearer token. The server is stateless, so every request must carry the token. Compare it in constant time:

src/env.ts
src/middleware.ts

Declare the connection with Flue's defineMcpConnection and mount it with useMcpConnection. Flue sends auth as Authorization: Bearer <token> on every request. tools is an allowlist of the server's tool names:

src/connection.ts
src/agents/assistant.ts

Flue names adapted tools mcp__<server>__<tool>, such as mcp__xmcp__get-shipping-policy. Adapted MCP tools run inside an agent turn. Mount the agent in src/app.ts with createAgentRouter and protect the route with your own middleware.

Expose a Flue agent as an xmcp tool

Call the deployed agent with createFlueClient. Use a new conversation per call so callers never share history:

src/agent-client.ts
src/tools/ask-agent.ts

Keep ask-agent out of the agent's own connection allowlist so the agent cannot call itself.

Errors and cancellation

ask-agent submits once and never retries, so a transient failure cannot run the agent twice. Failed runs, upstream errors, and empty replies return one generic tool error, and details stay in the agent server logs. Cancelling the MCP request stops reading the reply, but the agent may still finish its turn. Use the Flue client's abort() when you also need to stop the run.

Tested versions

@flue/runtime, @flue/sdk, and @flue/vite 2.3.0 with Vite 8. Flue 2.3.0 accepts @earendil-works/pi-ai ^1.1.0, but pi-ai 1.5 removed an export Flue imports. Pin Flue's @earendil-works/pi-ai and @earendil-works/pi-agent-core to 1.4.0 with your package manager's overrides until Flue publishes a fix.

The example's README covers environment variables, the agent server, and its tests.

One framework to rule them all