MDK App Toolkit
The three-layer MDK development toolkit — App Node backend, plugin system, and frontend packages
Overview
The MDK App Toolkit is the recommended development path for teams building MDK-powered applications. It is composed of three coordinated layers:
- Gateway backend
- Plugin system
- Frontend packages
Not every layer is required for every consumer type.
MDK supports two primary consumer patterns:
- Human operator UI: a frontend application connects to the Gateway's REST and WebSocket APIs. The full three-layer toolkit applies — Gateway, plugin system, and frontend packages
- AI agent / headless consumer: an AI agent connects to the Gateway's MCP endpoint and subscribes to telemetry feeds directly. The frontend packages are not required; the Gateway and plugin system alone are sufficient
Status: MCP is in progress. The HTTP and WebSocket consumer paths are available today.
Gateway layer
@tetherto/mdk-gateway is the backend component of the toolkit. It wraps @tetherto/mdk-client — the Kernel protocol connector —
and delivers an authenticated HTTP, WebSocket, and MCP interface for consumers that need those capabilities. Read the
Gateway concept page for the full developer model: extension patterns, data access, auth design, and Kernel connection.
As a toolkit component, the Gateway provides out of the box:
- Fastify-based HTTP server and WebSocket endpoint
- JWT authentication, session management, and OAuth2 (Google and Microsoft)
- RBAC enforcement at the route level
- Command proxying and telemetry subscriptions to Kernel via
@tetherto/mdk-client - MCP endpoint for AI agents
Using @tetherto/mdk-client without the Gateway runtime is technically possible — you write your own auth,
routing, and middleware — but it is not supported by this monorepo. Most applications build on the Gateway.
Plugin system
@tetherto/mdk-plugins is the extension mechanism. A plugin is a directory containing an mdk-plugin.json manifest and one or
more controller files. The Gateway discovers and loads plugins from directories passed via extraPluginDirs.
The toolkit ships defaults plugins, e.g., auth (user authentication routes), telemetry (hashrate, efficiency, temperature
metrics), and site-hashrate (aggregated site history). Any plugin you write loads identically.
- Plugin authoring guide — build process, manifest schema, controller contract
- Plugin reference — manifest schema, default routes, loader errors
Frontend packages
These packages are for the human operator UI pattern — the application layer that connects to the Gateway's REST and WebSocket APIs. If your consumer is an AI agent connecting via the MCP endpoint, this layer is not required.
Early versions of MDK ship three layered workspace packages within the monorepo. npm packages will be published as the tooling matures.
Consuming applications add the workspace dependencies directly. Consuming the whole chain is the recommended path for operator UIs.
The UI architecture reference covers the full dependency graph, build strategy, and package internals.
@tetherto/mdk-ui-foundation: framework-agnostic headless core. No React imports. Provides Zustand vanilla stores
(authStore, devicesStore, notificationStore, timezoneStore, actionsStore), a TanStack QueryClient factory with
environment-aware base URL resolution, centralised queryKeys and query factories for all read endpoints (including Op Centre reads —
site, racks, PDU layout, global data, thingConfig — and Pool Manager), Op Centre query parameter builders, the per-model container
detail-tab matrix, a null-safe envelope flattener (flattenKernelEnvelope), and the Gateway API type contracts.
@tetherto/mdk-react-adapter: React bindings for the core. Provides <MdkProvider apiBaseUrl={...}>
(required at the app root) and store hooks (useAuth, useDevices, useTimezone, useNotifications, useActions).
@tetherto/mdk-react-devkit: React UI library. src/primitives/ ships generic UI primitives built on Radix UI
(Button, Dialog, Switch, Select, Data Table, Charts). src/domain/ ships mining-domain components, features, and presentation hooks.
Developer entry points
The toolkit can be adopted at any of the following entry points, from most batteries-included to least.
| Entry point | Package | What ships | What you write | When to choose |
|---|---|---|---|---|
| UI Kit | @tetherto/mdk-react-devkit (/primitives + /domain entrypoints) | Pre-built React components, shell layout, ready-made ops dashboard | Data wiring, optional theming | You want a dashboard up fast |
| Framework adapter | @tetherto/mdk-react-adapter (React today; Vue/Svelte/WC planned) | <MdkProvider>, store hooks, TanStack Query re-exports | Your own components and layout | You have a design system already |
| UI Foundation | @tetherto/mdk-ui-foundation | Zustand vanilla stores, QueryClient factory, queryKeys, query factories, Op Centre query builders, container tab matrix, API types | Framework bindings or headless utilities | You need store access outside React or are building a new adapter |
| Raw SDK | @tetherto/mdk-client | MDK Protocol client, connection management, reconnection | Everything above the wire: state, framework, UI | You are building a non-UI consumer (CLI, agent, backend service) |
Architecture overview
Next steps
- Understand the Gateway surface
- Build or extend with the plugin system
- Explore the frontend package architecture