MDK App Toolkit

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 API and polls it for live data. The full three-layer toolkit applies — Gateway, plugin system, and frontend packages
• AI agent / headless consumer: an AI agent connects via the standalone @tetherto/mdk-mcp package. The frontend packages are not required

Gateway layer

@tetherto/mdk-gateway is the backend component of the toolkit. It wraps @tetherto/mdk-client — the Kernel protocol connector — and delivers an HTTP 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
• Declarative plugin loading, request-level caching, and manifest validation at startup
• Command proxying and telemetry access to Kernel via @tetherto/mdk-client

Agents can reach MDK over MCP through the standalone @tetherto/mdk-mcp package.

Authentication, session management, and RBAC are not included. Identity is yours to supply, invoked from the controllers that need it.

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 auto-loads several plugins and ships auth alongside, allowing you to provide your identity solution. Any plugin you write loads by the same mechanism.

Frontend packages

These packages are for the human operator UI pattern — the application layer that connects to the Gateway's REST API and polls it for live data. If your consumer is an AI agent connecting via MCP, this layer is not required.

Consuming applications add the workspace dependencies directly. Consuming the whole chain is the recommended path for operator UIs.

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

Architecture overview

Next steps

• Understand the Gateway surface
• Build or extend with the plugin system
• Explore the frontend package architecture