MCP Servers

Lazy initialization — MCP connections use a lazy initialization pattern for efficiency. When the agent loop starts, tool schemas are loaded from cached catalogs stored in the database — no server connection is needed. An actual connection to the MCP server is only established when the LLM first calls an MCP tool during a conversation. This means containers are not started and network connections are not opened unless the assistant actually needs to use MCP tools in that particular conversation.

Event loop architecture — The MCP connection manager runs a dedicated event loop in a background daemon thread. This is necessary because MCP sessions require persistent background I/O tasks for reading from and writing to transports (stdio pipes, SSE streams, or HTTP connections). The event loop stays alive between tool calls within a single agent loop, so the connection is reused for multiple tool calls. Connections are cleaned up when the agent loop finishes.

How caching works — After each successful connection to an MCP server, the discovered tools (names, descriptions, and parameter schemas) are persisted to the database. On subsequent conversations, these cached schemas are used to build the tool definitions sent to the LLM — without connecting to the server at all. This is essential for performance, as otherwise every conversation would need to start containers or open network connections just to tell the LLM what tools exist.

First connection — For servers that have never been connected (no cached tools), the system connects immediately during agent loop setup to discover their tools. The discovered tools are then persisted so subsequent conversations use the cache.

Cache invalidation — The cache is refreshed when you click Test Connection, when the server configuration changes (image, command, environment variables), or when the system detects that a running container has been recreated due to configuration changes.