Operator agent how-to guides

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 (:3101 in the MVP site example), and the agent's own Gateway (:3847) are three separate processes

  model  ──►  agent gateway  ──►  MCP tool server  ──►  kernel + workers
   :11500        :3847              :3101                  (the fleet)
                   ▲
                   └── UI shell :3030, proxying /agent

The agent connects to MCP once, when a session is created (the first POST /agent/sessions). If the tool server isn't up yet, the connection fails: the app answers 503 ERR_AGENT_UNAVAILABLE and tries again on the next request, so start the tool server and retry. The standalone CLI exits instead, with (is the MCP server running at <url>?). Only an agent with no mcp.url set runs with no tools, answering from the model alone.

mdk run mcp checks every agent against spec.rbac, so the agent signs in to it as its own service account, set under agent.mcp.credential. Without one, the connection is refused with 401 and the app answers 503 ERR_AGENT_UNAVAILABLE. Giving the agent a service account covers mdk sa add, the spec.rbac binding and the config.

Choose a guide

Exposing an app's own routes to the agent as tools is a detail of building an app, 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