BitFun: treating MCP as a lifecycle, not just a tool list

[bobleer]

Pre-submission Checklist

• This post follows the MCP community guidelines

What would you like to share?

Maintainer disclosure: I work on BitFun.

BitFun is a Rust-based desktop agent for Windows, macOS, and Linux. We use MCP
to connect external capabilities, but the implementation problem that consumed
most of our attention was not parsing a tool schema. It was owning the full
server lifecycle without creating a second, inconsistent tool runtime.

What we built

• Local MCP servers use stdio; remote servers use Streamable HTTP or SSE. The
  config model rejects invalid local/remote transport combinations instead of
  silently guessing.
• A single lifecycle manager owns registration, startup, health state,
  reconnection, and tool publication. Multiple desktop windows can request
  initialization without destructively restarting healthy servers.
• MCP tools enter the same typed catalog and execution path as built-in tools.
  MCP configuration and transport stay outside the agent loop; permission,
  result persistence, previews, and artifact references stay in the shared tool
  boundary.
• Session-scoped MCP servers are tracked separately from persisted servers so a
  temporary external session can be retired without tearing down unrelated
  user configuration.

What was harder than expected

Configuration is not runtime state. A config file can say that a server is
enabled while the process is starting, waiting for auth, reconnecting, or has
already been superseded by a newer session. Publishing tools before that state
transition is complete leaves stale entries in the model-visible catalog.

The second boundary appeared when we added Agentic Mini Apps: task output can
become a persistent chart, board, form, or control panel instead of ending as a
transcript. We deliberately keep that UI/artifact layer separate from MCP. MCP
provides external capabilities; the Mini App is a session-bound presentation
and state surface, not another place that can bypass tool permissions.

What we learned

1. Give MCP lifecycle one owner. Do not let each UI window, session adapter, or
   plugin build its own connection pool.
2. Publish a tool only after the corresponding runtime state is current, and
   make cleanup idempotent.
3. Treat oversized results and durable artifacts as first-class execution
   concerns rather than pushing every byte back into the model context.
4. Keep the protocol adapter thin; permission and audit semantics should not
   change depending on whether a tool is built in or came from MCP.

I would value feedback from other MCP host implementers on two questions:

• How are you representing a durable artifact or UI state that outlives the
  individual tool call without making the protocol session own application
  state?
• Have you found a clean interoperability test for reconnect + catalog refresh
  behavior across stdio and Streamable HTTP servers?

Relevant Links

• Repository: https://github.com/GCWing/BitFun
• Transport and config validation:
  https://github.com/GCWing/BitFun/blob/bd47cc51659b2a0525fe05dc18ae7bb25ae51ef8/src/crates/services/services-integrations/src/mcp/server/mod.rs#L35-L65
• Lifecycle and tool registration:
  https://github.com/GCWing/BitFun/blob/bd47cc51659b2a0525fe05dc18ae7bb25ae51ef8/src/crates/assembly/core/src/service/mcp/server/manager/lifecycle.rs#L175-L280
• Tool/MCP ownership boundary:
  https://github.com/GCWing/BitFun/blob/bd47cc51659b2a0525fe05dc18ae7bb25ae51ef8/docs/architecture/agent-runtime-services-design.md#L639-L658
• Mini Apps architecture note:
  Your AI task should not end as a chat transcript GCWing/BitFun#2113