# How the OpenHuman MCP Registry Manages Dynamic Servers and OAuth Flows

> Discover how the OpenHuman MCP registry manages dynamic servers and OAuth flows through in-memory mapping and automated auth code exchanges for seamless runtime discovery and secure authentication.

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

---

**The OpenHuman MCP registry maintains an in-memory map of server entries and automates OAuth 2.0 authorization code exchanges, enabling runtime discovery and secure authentication without service restarts.**

The MCP (Message Control Protocol) registry serves as the central nervous system for the OpenHuman framework, orchestrating how the system discovers, registers, and communicates with external services. According to the `tinyhumansai/openhuman` source code, this registry implements a plug-and-play architecture that allows **dynamic servers**—services added or removed at runtime—to integrate seamlessly while handling **OAuth 2.0 flows** transparently through automated token management.

## Registry Architecture and Core Components

The registry implementation spans six modular files in `src/openhuman/mcp/registry/`,each handling distinct responsibilities:

- **Registry Core** ([`mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/mod.rs)): Maintains the in-memory map of `McpServerEntry` objects containing URL, client ID, scopes, and encrypted tokens.
- **Operations** ([`ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/ops.rs)): Exposes JSON-RPC methods like `mcp_registry_add_server` and `mcp_registry_list_servers` for runtime CRUD operations.
- **Schemas** ([`schemas.rs`](https://github.com/tinyhumansai/openhuman/blob/main/schemas.rs)): Defines request/response types including `McpRegistryAddServerInput` and `McpRegistryListServersOutput`.
- **Event Bus** ([`bus.rs`](https://github.com/tinyhumansai/openhuman/blob/main/bus.rs)): Publishes `DomainEvent::McpServerAdded` and `DomainEvent::McpServerRemoved` for decoupled subsystem communication.
- **Setup Operations** ([`setup_ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/setup_ops.rs)): Handles OAuth authorization code exchange, token refresh scheduling, and error propagation.
- **Helpers** ([`helpers.rs`](https://github.com/tinyhumansai/openhuman/blob/main/helpers.rs)): Provides URL validation, redirect URI construction, and secure token persistence utilities.

## Runtime Server Registration

### Adding Servers via JSON-RPC

Clients interact with the registry through the `mcp_registry_add_server` RPC method. As implemented in [`src/openhuman/mcp/registry/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/registry/ops.rs), the `ops::add_server` function processes an `AddServerInput` struct:

```rust
use openhuman::mcp::registry::ops::{self, AddServerInput};

let input = AddServerInput {
    url: "https://api.example.mcp".into(),
    client_id: "my-client-id".into(),
    scopes: vec!["read".into(), "write".into()],
    client_secret: Some("super-secret".into()),
    requires_oauth: true,
};

match ops::add_server(&input) {
    Ok(entry) => println!("Server added with id {}", entry.id),
    Err(e) => eprintln!("Failed: {}", e),
}

```

When invoked, the function instantiates a new `McpServerEntry`, inserts it into the registry's internal map, and emits a `DomainEvent::McpServerAdded` event across the bus. If the server entry specifies `requires_oauth: true`, the registry automatically initiates the OAuth setup flow.

### Schema Validation

The [`schemas.rs`](https://github.com/tinyhumansai/openhuman/blob/main/schemas.rs) module validates incoming payloads against strict Rust types. A registration request must include the server URL and OAuth requirements, while the response returns the generated server ID and current authentication state.

## OAuth 2.0 Flow Automation

The registry internalizes all OAuth complexity, implementing the authorization code flow without exposing credential handling to other components.

### Authorization Code Exchange

When `requires_oauth: true`, the registry initiates a six-step process defined in [`setup_ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/setup_ops.rs):

1. **Redirect Generation**: `helpers::create_oauth_redirect_uri` constructs the authorization URL with CSRF-protected state tokens.
2. **User Authorization**: The system redirects users to the external server's `/oauth/authorize` endpoint.
3. **Callback Processing**: Upon return to the `mcp/oauth/callback` endpoint, `setup_ops::exchange_code_for_token` executes.
4. **Token Retrieval**: The function POSTs the authorization code to the server's `/oauth/token` endpoint.
5. **Secure Storage**: Access and refresh tokens encrypt into the `McpServerEntry::token` field.
6. **Error Propagation**: Failures generate `DomainEvent::McpOAuthError` events and return `McpRegistryError::OAuthFailed` via JSON-RPC.

```rust
use openhuman::mcp::registry::setup_ops;

async fn oauth_callback(query: HashMap<String, String>) -> impl Responder {
    let code = query.get("code").cloned().unwrap();
    let state = query.get("state").cloned().unwrap();

    match setup_ops::exchange_code_for_token(&code, &state).await {
        Ok(_) => HttpResponse::Ok().body("Authorization successful!"),
        Err(err) => HttpResponse::BadRequest().body(format!("OAuth error: {}", err)),
    }
}

```

### Automatic Token Refresh

The registry schedules background refresh tasks via `setup_ops::schedule_refresh`. This monitors token expiry and silently exchanges refresh tokens for new access credentials, updating the server entry without user intervention or service disruption.

## Event-Driven Lifecycle Management

The [`bus.rs`](https://github.com/tinyhumansai/openhuman/blob/main/bus.rs) module implements a publish-subscribe pattern that decouples server management from client connections. Subscribers receive strongly-typed events:

```rust
bus::subscribe_global(|event| match event {
    DomainEvent::McpServerAdded(entry) => client.connect(entry),
    DomainEvent::McpServerRemoved(id) => client.disconnect(id),
    DomainEvent::McpOAuthError{id, err} => ui.show_error(id, err),
    _ => {}
});

```

This architecture enables hot-plugging: the MCP client connects immediately upon `McpServerAdded` and cleans up on `McpServerRemoved` without polling the registry. JavaScript clients can subscribe using:

```javascript
import { subscribeGlobal } from '@openhuman/core/event_bus';

subscribeGlobal(event => {
  if (event.type === 'McpServerAdded') {
    console.log('New MCP server:', event.entry);
  } else if (event.type === 'McpServerRemoved') {
    console.log('MCP server removed:', event.id);
  }
});

```

## Runtime Query and Mutation Operations

Beyond registration, the registry supports full lifecycle management through additional RPC methods implemented in [`ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/ops.rs):

- **`mcp_registry_list_servers`**: Returns all active entries with their authentication states (`authenticated: true/false`).
- **`mcp_registry_remove_server`**: Deletes the entry, triggers `DomainEvent::McpServerRemoved`, and signals the client to close connections.
- **`mcp_registry_update_server`**: Modifies scopes, client IDs, or URLs. If OAuth parameters change, the registry automatically restarts the setup flow to re-authenticate.

## Summary

- The OpenHuman MCP registry maintains an in-memory map of `McpServerEntry` objects in [`src/openhuman/mcp/registry/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/registry/mod.rs), tracking dynamic server configurations and encrypted OAuth tokens.
- **Runtime registration** occurs through JSON-RPC methods like `mcp_registry_add_server`, which validate input via [`schemas.rs`](https://github.com/tinyhumansai/openhuman/blob/main/schemas.rs) and emit lifecycle events via [`bus.rs`](https://github.com/tinyhumansai/openhuman/blob/main/bus.rs).
- **OAuth 2.0 flows** are fully automated in [`setup_ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/setup_ops.rs), handling authorization code exchange, secure token storage, and background refresh without exposing credentials to other subsystems.
- The **event-driven architecture** uses `DomainEvent` variants to notify clients of server additions, removals, and authentication errors, enabling hot-pluggable service integration.
- All **CRUD operations** support runtime modification of server configurations, with automatic re-authentication when OAuth scopes or credentials change.

## Frequently Asked Questions

### What is the MCP registry in OpenHuman?

The MCP registry is a centralized Rust module in the OpenHuman framework that manages connections to external MCP (Message Control Protocol) servers. It maintains an in-memory registry of server configurations, handles OAuth 2.0 authentication flows, and publishes lifecycle events to coordinate with other system components like the MCP client and UI dashboards.

### How does the registry handle OAuth token expiration?

According to [`src/openhuman/mcp/registry/setup_ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/registry/setup_ops.rs), the registry schedules automatic refresh tasks using `setup_ops::schedule_refresh`. This background process monitors token expiry times and silently exchanges refresh tokens for new access credentials, updating the encrypted `McpServerEntry::token` field without requiring user re-authentication or system restarts.

### Can I add MCP servers while the OpenHuman system is running?

Yes. The registry supports **dynamic server registration** through the `mcp_registry_add_server` JSON-RPC method implemented in [`ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/ops.rs). When called, the system immediately creates a `McpServerEntry`, emits a `DomainEvent::McpServerAdded` event, and—if OAuth is required—initiates the authorization flow, all without restarting the core application.

### Which files should I examine to understand the registry's OAuth implementation?

The OAuth 2.0 implementation spans three primary files: [`src/openhuman/mcp/registry/setup_ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/registry/setup_ops.rs) contains the token exchange and refresh logic; [`src/openhuman/mcp/registry/helpers.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/registry/helpers.rs) provides URL validation and redirect construction; and [`src/openhuman/mcp/registry/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/mcp/registry/mod.rs) defines the `McpServerEntry` struct that stores encrypted tokens.