MCP Server Architecture
A modular C++26 platform built around the Model Context Protocol, designed for extensibility and real-time communication.
Server Core
The MCP server is a C++26 application using cinatra for high-performance async HTTP and WebSocket handling with C++20 coroutines. It implements JSON-RPC 2.0 for tool discovery, execution, and notifications. Plugins are loaded dynamically via dlopen and can be hot-reloaded without restarting the server.
Design Constraints
Four requirements shaped the toolchain. Each tool call has a latency budget under 5 ms, because an agent loop issues dozens of calls per reasoning step. Plugins reload without restarting the host, so connected clients and long-running jobs keep running. One backend serves four clients : Native, web, WASM and command line. The same process hosts inference, vector search and plugin code, which requires explicit control of memory and GPU buffers. The reasoning behind each requirement, and the choice of C++26 with GCC 16, is in Why We Built Our MCP Server in C++26.
Tool Declaration
Each plugin registers its tools in the ToolRegistry, with a JSON Schema for the input of each tool. The SDK uses C++26 static reflection (P2996) for compile-time introspection of enums and structs : The header Mcp/Reflect.h reads enumerator and member names at compile time. The reflection primitives and the GCC 16 build flags are covered in C++26 Reflection in Production.
Native Client
A desktop application built with SDL2 and OpenGL, using ImGui (docking branch) for the UI. Each plugin opens in its own dockable window. Client plugins follow hexagonal architecture: Domain, AppService/ViewModel, ServerProxy, and UI Panels.
Web Client
Angular applications connecting to MCP servers via WebSocket. Currently powers the BI Viewer (report visualization with ECharts). Supports SSR pre-rendering for static deployment.
Plugin System
Server Plugins
Shared libraries (.so) exposing tools via a C ABI factory. Each plugin registers tools in a ToolRegistry with JSON Schema validation. Plugins communicate in-process via IPluginResolver.
Client Plugins
Shared libraries loaded by the native client. Each renders its own ImGui window and communicates with the server via callTool. Follows SOLID/hexagonal architecture.
Hot-Reload
The server watches plugin .so files for changes. When detected, the plugin is unloaded and reloaded with state preservation. No server restart required.
Reload Sequence
A plugin reload runs eight steps. The host detects a new artefact, asks the old plugin to quiesce under a drain timeout, takes the registry write lock, and closes the old handle with dlclose. It opens the new handle with dlopen and checks the build identifier embedded in the plugin against the file on disk. It then releases the lock, runs initialize() on a detached thread, retakes the lock briefly to publish the tools, and emits a reload notification. The three constraints behind these steps are in Plugin Hot-Reload in C++ : Three dlopen Constraints.
Communication Protocol
All communication uses the Model Context Protocol over WebSocket with JSON-RPC 2.0. The server pushes CDC notifications to connected clients for real-time synchronization.
Tool Discovery
Clients query available tools with their JSON Schema input definitions, namespaced by plugin.
Session Management
RBAC authentication via rbac_login. Sessions are tied to WebSocket connections with user context injected into every tool call.
Change Data Capture
Write tools trigger notifications. Clients receive real-time updates to refresh their UI when server data changes.
Access Control
Access is decided at tool dispatch. Each session opens with a set of allowed tool prefixes, one prefix per plugin, and a call outside that set is rejected before any plugin code runs. The agent-side ToolBridge rejects such a call locally, without a round trip. The server applies the same policy as the authoritative check, whatever client sent the call. The role model and the audit trail are described in RBAC and Audit Logging for MCP.
Related
The ports-and-adapters discipline that keeps this core independent of its clients is described in Hexagonal Architecture for MCP Plugins. We install and operate this architecture for client organisations as MCP server deployment.