Operator agent how-to guides
Task guides for running MDK's conversational operator agent, standalone or behind the Gateway
Overview
@tetherto/mdk-agent is a conversational operator agent that answers plain-language questions about a mining fleet, calls
fleet tools over MCP, and gates writes behind human approval. What the agent is and how it fits the stack
covers the concepts; these guides cover running it.
The agent never rides on another stack's own Gateway. A model (:11500), an MCP tool server (:3008 in the
full-site example), and the agent's own Gateway (:3847) are three separate processes
Full-site's own Gateway (:3007) has no /agent routes at all.
model ──► agent gateway ──► MCP tool server ──► kernel + workers
:11500 :3847 :3008 (the fleet)
▲
└── UI shell :3030, proxying /agentThe agent connects to MCP once, when a session is created (the first POST /agent/sessions), so a session started before
the tool server is up gets no tools and answers from the model alone, with no error to tell you.
Choose a guide
| Goal | Guide |
|---|---|
| Run the agent as a standalone CLI, for local development or evaluation | Run the agent as a standalone CLI |
| Deploy the agent behind the Gateway as a chat API for an operator UI | Deploy the agent behind the Gateway |
| Score a battery run against a fleet and compare models | Evaluate the agent |
Exposing a plugin's own routes to the agent as tools is a detail of building Gateway plugins, not its own deployment path. See Expose data to the agent there.
Next steps
- If Gateway, Kernel, or plugin are unfamiliar, see the terminology
- Understand the agent as a stack component
- Understand the Gateway as a development surface