How the MCP Registry Handles Dynamic Smithery Server Installs in OpenHuman

The MCP registry handles dynamic Smithery server installs by downloading verified bundles, persisting server metadata to SQLite, and automatically establishing STDIO or HTTP connections through the McpSetupInstallAndConnectTool.

The MCP (Micro-Command-Protocol) registry is the core component in the tinyhumansai/openhuman repository that manages both static configuration-defined servers and dynamic Smithery servers. When users need to extend functionality on-the-fly, the registry orchestrates secure downloads, persistent storage, and live connection management without requiring manual configuration edits.

The Install-and-Connect Workflow

When a user initiates a dynamic server installation, the registry executes a five-phase process that bridges the Smithery package ecosystem with the OpenHuman runtime.

1. Tool Invocation via McpSetupInstallAndConnectTool

The entry point for dynamic installs is the McpSetupInstallAndConnectTool, implemented in src/openhuman/tools/impl/network/mcp_setup.rs. This UI-facing tool receives a Smithery URL or Git reference along with optional authentication parameters. According to the source code, the tool constructs an InstallArgs structure containing the server location and install flags before delegating to the registry core.

let install_tool = McpSetupInstallAndConnectTool::new(cfg.clone());
let args = InstallArgs {
    url: "https://smithery.tinyhumans.ai/my-mcp-server".into(),
    auth: None,
};
let result = install_tool.run(args).await?;
println!("Installed server UUID: {}", result.server_id);

2. Smithery Bundle Download and Verification

Once invoked, the tool utilizes the Smithery client to download the server bundle from the specified URL. The client verifies the bundle's integrity using SHA-256 checksums before unpacking the contents into the core's dedicated Smithery cache directory. This verification step ensures that only cryptographically valid server code enters the local execution environment.

3. Server Registration in the MCP Registry

After successful extraction, the tool calls McpServerRegistry::install_server, defined in src/openhuman/mcp/registry/ops.rs. This function creates a new McpServerRecord containing the server's name, host address, authentication method, and a generated UUID. The registry then persists this record to the SQLite database at mcp_servers.db located in the user's .openhuman workspace, with database connectivity provided by src/openhuman/mcp/registry/bus.rs.

impl McpServerRegistry {
    pub async fn install_server(&self, spec: McpServerSpec) -> Result<McpServerId> {
        let record = McpServerRecord::from_spec(spec);
        self.db.insert(&record).await?;
        self.active.insert(record.id, record.clone());
        Ok(record.id)
    }
}

4. Automatic Connection Establishment

Immediately following registration, the tool invokes McpServerRegistry::connect_server to establish a live session. The registry inspects the server's advertised transport type and initializes either a STDIO-based MCP session via src/openhuman/mcp/server/stdio.rs or an HTTP session via src/openhuman/mcp/server/http.rs. Successful connections populate the registry's in-memory map of active servers, making the dynamically installed server immediately available for command routing.

5. Health Diagnostics and Monitoring

The registry maintains observability through McpAllowlistDiagnostics and McpWriteAuditHealth structures. These diagnostics are updated by helper functions within src/openhuman/mcp/registry/ops.rs, enabling the UI to display real-time health status for each dynamic server without polling the underlying transport directly.

Persistence and State Management

The MCP registry is architected to remain stateless across process restarts. While the in-memory map of active servers is ephemeral, the SQLite database in .openhuman/mcp_servers.db ensures that dynamically installed servers survive core restarts. At startup, the registry invokes McpServerRegistry::load_from_db to reconstruct the runtime state by reading persisted records, effectively rebuilding the active server map from the durable store.

Listing and Managing Dynamic Servers

To retrieve both static and dynamic servers, the system exposes the McpListServersTool (located in src/openhuman/tools/impl/network/mcp.rs). This tool queries the SQLite database and returns a unified list of all configured MCP servers, regardless of their installation origin.

let list_tool = McpListServersTool::new(Arc::new(registry));
let servers = list_tool.run(()).await?;
for s in servers {
    println!("{} – {}", s.name, s.endpoint);
}

Summary

• The McpSetupInstallAndConnectTool in mcp_setup.rs serves as the UI gateway for initiating dynamic Smithery server installations.
• SHA-256 verification ensures bundle integrity before the Smithery client unpacks server code into the cache directory.
• McpServerRegistry::install_server creates persistent McpServerRecord entries in SQLite via src/openhuman/mcp/registry/bus.rs.
• Automatic connection selects between STDIO and HTTP transports based on server capabilities, managed by connect_server in ops.rs.
• Stateless durability is achieved through SQLite persistence, with load_from_db rebuilding runtime state at startup.

Frequently Asked Questions

What is the MCP registry in OpenHuman?

The MCP registry is the centralized management component in tinyhumansai/openhuman that discovers, tracks, and maintains connections to MCP servers. It handles both statically configured servers defined in user configuration files and dynamic servers installed on-demand through the Smithery ecosystem, providing a unified interface for server lifecycle management.

How does the MCP registry persist dynamic server installations?

The registry persists dynamic servers using a SQLite database located at .openhuman/mcp_servers.db. When McpServerRegistry::install_server processes a new Smithery bundle, it writes a McpServerRecord containing the server's metadata and UUID to this database. This design ensures that dynamic installations survive process restarts, with the registry reconstructing its in-memory active server map by reading from this database at startup.

What transport protocols does the MCP registry support for dynamic servers?

According to the source code in src/openhuman/mcp/server/, the MCP registry supports two primary transport protocols for dynamic servers: STDIO-based sessions (stdio.rs) for local process communication and HTTP-based sessions (http.rs) for network-accessible servers. The McpServerRegistry::connect_server method automatically selects the appropriate transport based on the server's advertised capabilities in its persisted record.

How does McpSetupInstallAndConnectTool differ from manual server configuration?

McpSetupInstallAndConnectTool automates the entire installation pipeline that manual configuration requires users to perform separately. While manual configuration involves editing config files and manually downloading server binaries, this tool handles Smithery URL resolution, cryptographic verification, SQLite registration, and immediate connection establishment in a single atomic operation exposed through the OpenHuman UI.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}