# How the MCP Registry Handles Dynamic Smithery Server Installs in OpenHuman

> Learn how the MCP registry handles dynamic Smithery server installs in OpenHuman. Discover verified bundle downloads, metadata persistence, and connection setup with McpSetupInstallAndConnectTool.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: internals
- Published: 2026-08-24

---

**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`](https://github.com/tinyhumansai/openhuman/blob/main/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.

```rust
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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/registry/bus.rs).

```rust
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`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/server/stdio.rs) or an **HTTP session** via [`src/openhuman/mcp/server/http.rs`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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.

```rust
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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/stdio.rs)) for local process communication and **HTTP-based sessions** ([`http.rs`](https://github.com/tinyhumansai/openhuman/blob/main/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.