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

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, 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 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, 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 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 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 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. 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 provides async helpers for managing Smithery server lifecycles programmatically.

Listing connected servers:

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

Connecting a new Smithery server:

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:

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

Handling OAuth callbacks:

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.

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, 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. 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.

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