Skip to content
🏮 Hatago MCP Hub

System Architecture

Principles

Section titled “Principles”
  • Lightweight core
  • Transparent MCP forwarding
  • Extensible transports and servers

System Overview

Section titled “System Overview”

Package Dependencies

Section titled “Package Dependencies”

Security & Performance

Section titled “Security & Performance”
  • Process isolation per child server
  • Lazy initialization
  • Optional metrics endpoint in HTTP mode (/metrics, opt‑in via HATAGO_METRICS=1)

See also: Data Flow (coming soon), Config Reference.

Core Components

Section titled “Core Components”
class Hub {
  // Lifecycle
  async start(options: HubOptions): Promise<void>;
  async stop(): Promise<void>;


  // Request handling
  async handleRequest(req: JSONRPCRequest): Promise<JSONRPCResponse>;


  // Notification forwarding
  async forwardNotification(n: JSONRPCNotification): Promise<void>;
}

Responsibilities:

  • Manage child server lifecycle
  • Route requests to the right server
  • Aggregate tools/resources/prompts
  • Forward progress and other notifications

Server Registry

Section titled “Server Registry”
interface ServerRegistry {
  registerLocal(id: string, cfg: LocalConfig): void;
  registerNPX(id: string, cfg: NPXConfig): void;
  registerRemote(id: string, cfg: RemoteConfig): void;
}

Session Manager

Section titled “Session Manager”
interface SessionManager {
  createSession(clientId: string): Session;
  getServerInstance(sessionId: string, serverId: string): MCPServer;
  destroySession(sessionId: string): void;
}

Performance

Section titled “Performance”

Lazy init

Section titled “Lazy init”
async callTool(name: string, args: any) {
  const server = await this.lazyInitServer(name);
  return server.callTool(name, args);
}

Connection pooling (remote)

Section titled “Connection pooling (remote)”
class ConnectionPool {
  private connections = new Map<string, Connection>();
  async getConnection(url: string) {
    if (this.connections.has(url)) return this.connections.get(url)!;
    const conn = await this.createConnection(url);
    this.connections.set(url, conn);
    return conn;
  }
}

Extension Points

Section titled “Extension Points”
class CustomServer implements MCPServer {
  async initialize(cfg: CustomConfig) {/* ... */}
  async listTools() {/* ... */}
  async callTool(name: string, args: any) {/* ... */}
}


registry.register('custom', CustomServer);

Custom transports can implement a common Transport interface and be plugged under the hub.

Roadmap (high level)

Section titled “Roadmap (high level)”
  • Short‑term: improved error recovery, perf insights, Bun/Deno adapters
  • Long‑term: WASM, browser runtime, distributed clustering

Internal Resource

Section titled “Internal Resource”
  • hatago://servers — JSON snapshot of connected servers (id/status/type/tools/resources/prompts).
Section titled “Related”