# How the MCP Registry Integrates Dynamic Smithery Servers with OAuth and Supervisor Management in OpenHuman

> Explore how the MCP registry in OpenHuman integrates dynamic Smithery servers with OAuth and supervisor management. Learn about connection management and automatic reconnection.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: architecture
- Published: 2026-09-01

---

**The MCP registry in OpenHuman acts as a workspace-aware host component that bridges local AI agents to remote Smithery servers through modular subsystems for connection management, OAuth authentication, and automatic supervisory reconnection with exponential back-off.**

The **MCP (Multi-Channel Protocol) registry** serves as the central host-side component in the OpenHuman repository, enabling seamless interaction with dynamic **Smithery servers**—remote services that expose tools via the MCP contract. This registry architecture coordinates authentication, persistent connections, and fault-tolerant supervision across workspace-isolated environments. Understanding how the MCP registry integrates dynamic Smithery servers with OAuth and supervisor management reveals the robust Rust-based foundation that supports reliable third-party tool integration.

## Modular Architecture of the MCP Registry

The registry implementation follows a modular design pattern, with each subsystem handling a specific aspect of the server lifecycle. All components are conditionally compiled under the `mcp` feature flag and re-exported through **[`src/openhuman/mcp/registry/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/registry/mod.rs)**, which serves as the central hub for the public API.

The architecture centers on a **per-workspace service instance** pattern using `tinymcp::Service`, ensuring complete isolation when multiple workspaces operate within the same process. This service bundles the SQLite store, live connection map, and OAuth components into a cohesive unit managed by the `host` module.

## Core Registry Modules and Responsibilities

### Host Management and Service Instances

The `host` module in **[`src/openhuman/mcp/host.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/host.rs)** manages the lifecycle of `tinymcp::Service` instances. It provides workspace-aware helpers for creating, locating, and configuring services.

Key functions include:

- `host::for_config` – Creates or retrieves a service for a specific workspace configuration
- `host::try_service` – Returns the default workspace service
- `host::all_hosts` – Enumerates all active hosts across workspaces for supervisor operations
- `host::client_config` – Generates client-facing configuration objects

### Connection Lifecycle Management

Located in **[`src/openhuman/mcp/registry/connections.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/registry/connections.rs)**, the `connections` module offers an asynchronous interface to the live connection map supplied by the host service. It handles the dynamic discovery and manipulation of Smithery server connections without blocking the main runtime.

Primary capabilities include:

- `connections::connected_overview` – Lists all connected servers with current status
- `connections::all_connected_tools` – Aggregates tool catalogs from active connections
- `connections::connect` – Initiates new server connections with configuration validation
- `connections::disconnect` – Gracefully terminates specific server connections by ID

### OAuth Authentication Flow

The `oauth` module in **[`src/openhuman/mcp/registry/oauth.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/registry/oauth.rs)** manages browser-based authentication for Smithery servers requiring OAuth. When users authorize third-party access through the UI, the callback handler invokes `oauth::complete`, which performs the authorization code exchange.

This function receives the `state` and `code` parameters from the redirect, forwards them to `host::for_config(...).dynamic().oauth_complete`, stores the resulting access token in the workspace cache, and immediately triggers `connections::connect` to bring the authenticated server online.

### Supervisory Control and Resilience

The `supervisor` module in **[`src/openhuman/mcp/registry/supervisor.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/registry/supervisor.rs)** implements a background Tokio task that monitors connection health across all workspaces. Running continuously after boot, `supervisor::run` ticks at intervals defined by `SupervisorConfig::tick_interval`.

For each host returned by `host::all_hosts`, the supervisor creates or reuses a `tinymcp::Supervisor` instance and executes `Supervisor::tick`. This routine inspects the connection map, identifies dropped connections, and executes reconnection attempts using exponential back-off strategies. Failed reconnections are logged as warnings but never abort the supervisor loop, ensuring continuous resilience.

### Boot-Time Initialization

During core startup, the `boot` module in **[`src/openhuman/mcp/registry/boot.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/registry/boot.rs)** executes `boot::spawn_installed_servers`. This function iterates over every enabled `InstalledServer` entry in the workspace's `mcp_clients` table configuration.

It delegates to `tinymcp::registry::connect_installed_servers`, which attempts parallel connections via `connections::connect`. Boot failures are logged as warnings but never abort the initialization process, allowing partial availability when specific Smithery endpoints are unreachable.

### Tool Safety Validation

Before exposing remote tools to AI agents, the registry filters definitions through `tools_safe_for_agent` in **[`src/openhuman/mcp/registry/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/registry/mod.rs)**. This function scans each tool's description using OpenHuman's prompt-injection detector (`scan_tool_definition`).

Unsafe tools are omitted from the agent's available toolset, trigger a warning log entry, and publish a `DomainEvent::McpToolRejected` event. This security layer ensures that malicious or compromised Smithery servers cannot inject harmful instructions into the agent's context window.

## Runtime Integration Flow

The complete lifecycle from workspace initialization to active tool usage follows a deterministic sequence:

**Service Creation.** When a workspace opens, `host::for_config` instantiates a `tinymcp::Service` bundling the store, connection manager, and OAuth handler. For default workspaces, `host::try_service` provides quick access without configuration reloading.

**Boot-Time Connection.** The startup sequence invokes `boot::spawn_installed_servers`, reading the workspace configuration and attempting connections to all enabled servers. Successful connections populate the live connection map monitored by the async runtime.

**Supervisor Loop.** Post-boot, `supervisor::run` spawns persistent monitoring tasks. At each tick interval, the supervisor checks connection health and executes back-off reconnections for any dropped Smithery servers, updating the SQLite cache with status changes.

**OAuth Completion.** When users authenticate through the browser flow, the redirect handler calls `oauth::complete`. This exchanges the authorization code for tokens, persists credentials to the workspace store, and immediately re-establishes the server connection through the connections module.

**Tool Ingestion.** Upon connection, servers advertise their tool catalogs via `connections::tools_for`. The registry passes these through `tools_safe_for_agent`, filtering out unsafe definitions before surfacing tools to higher-level consumers like the MCP tool playground UI.

## Working with the Registry API

The public API exposed through **[`src/openhuman/mcp/registry/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/registry/mod.rs)** provides async helpers for managing Smithery server lifecycles programmatically.

Listing connected servers:

```rust
let overview = openhuman::mcp::registry::connections::connected_overview().await;
for server in overview {
    println!("{} ({})", server.server_id, server.status);
}

```

Connecting a new Smithery server:

```rust
let cfg = Config::load_or_init()?;
let server = tinymcp_bus::InstalledServer {
    server_id: "my-smithery".into(),
    // endpoint, auth_method, enabled fields...
};
let tools = openhuman::mcp::registry::connections::connect(&cfg, &server).await?;
println!("Connected, advertised {} tools", tools.len());

```

Disconnecting by identifier:

```rust
let was_connected = openhuman::mcp::registry::connections::disconnect("my-smithery").await;
println!("Was connected? {}", was_connected);

```

Handling OAuth callbacks:

```rust
async fn oauth_callback(state: &str, code: &str) -> Result<String, String> {
    let cfg = Config::load_or_init()?;
    openhuman::mcp::registry::oauth::complete(&cfg, state, code).await
}

```

## Summary

- The **MCP registry** operates as a workspace-isolated host component that bridges OpenHuman to remote Smithery servers through the Multi-Channel Protocol.
- **Per-workspace service instances** managed by `host::for_config` ensure complete isolation between different configuration contexts.
- **OAuth authentication** flows through `oauth::complete`, which exchanges authorization codes and immediately establishes authenticated connections via the dynamic API.
- The **supervisor module** provides automatic resilience through exponential back-off reconnection strategies for dropped server connections.
- **Tool safety filtering** via `tools_safe_for_agent` prevents prompt-injection attacks by scanning all remote tool definitions before agent exposure.
- All registry functionality gates behind the `mcp` feature flag, with the central API exposed through [`src/openhuman/mcp/registry/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/registry/mod.rs).

## Frequently Asked Questions

### What role does tinymcp::Service play in the MCP registry?

The `tinymcp::Service` acts as the central bundle containing the SQLite store, connection map, and OAuth components for a specific workspace. The `host` module creates and caches these service instances per workspace configuration, ensuring that connection states, authentication tokens, and cached responses remain isolated between different workspaces operating in the same process.

### How does OpenHuman authenticate with Smithery servers requiring OAuth?

When users initiate a connection to an OAuth-enabled Smithery server, OpenHuman opens a browser window to the server's authorization endpoint. After user consent, the redirect triggers `oauth::complete` in [`src/openhuman/mcp/registry/oauth.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/registry/oauth.rs), which exchanges the authorization code for an access token through the `dynamic().oauth_complete` method, stores the credentials in the workspace cache, and immediately invokes `connections::connect` to bring the server online with valid authentication.

### What happens when a Smithery server connection drops during operation?

The `supervisor::run` background task detects disconnected servers during its tick cycle through `tinymcp::Supervisor`. It implements an exponential back-off strategy, attempting reconnection at increasing intervals without blocking other operations. The supervisor updates the connection status in the store after each attempt, ensuring the UI reflects current availability while continuously working to restore connectivity.

### How does the registry protect against malicious tool definitions from Smithery servers?

Before exposing tools to the AI agent, the registry passes all advertised tool definitions through `tools_safe_for_agent` in [`src/openhuman/mcp/registry/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/registry/mod.rs). This function utilizes `scan_tool_definition` to detect prompt-injection attempts. Any unsafe tools are filtered from the agent's toolset, trigger warning logs, and emit `DomainEvent::McpToolRejected` events, preventing compromised servers from manipulating the agent through crafted tool descriptions.