Giving an Agent Control of a Local TDK Stack

Description and use

Automating control of a local TDK stack with an agent using the MCP server and TDK CLI tools

Problem

How to enable an AI agent to manage a local TDK stack reliably

Outcome

An agent can autonomously start, monitor, and stop a local TDK stack, reducing manual intervention and speeding up debugging cycles

Workflow

• Install TDK CLI
• Run tdk doctor --json to verify host capabilities
• Configure the MCP server in the agent client (e.g., Codex or Claude Code) to point to the TDK project
• Use the MCP tools (doctor, up, down, status, logs, resource_list) to control the stack
• Poll status until data.tilt.readiness.ready is true after up
• Handle errors via typed exit codes
• Log every tool call for review
• Test the loop on a throwaway project before production use

Evidence

TDK CLI is not an AI model and does not decide what to build. It is a local tool that describes a stack in service.json files and runs it with Docker and Tilt.

Source

The MCP server exposes six tools: doctor, up, down, status, logs, and resource_list.

Source

Run tdk doctor --json to verify host capabilities before handing anything to an agent.

Source