DEV Community

tdk-cli
tdk-cli

Posted on

TDK CLI Core and AI Agents: Connecting Claude and Codex Over MCP

#mcp #tdk #claude #ai

An AI coding agent is more reliable when it can check the running system instead of guessing at it. TDK CLI Core includes a local Model Context Protocol (MCP) server, started with tdk mcp, that exposes the local stack as tools an agent can call.

The tools

The server exposes six tools: doctor, up, down, status, logs, and resource_list. Each one runs the matching command in JSON mode, so the agent receives structured results rather than free text. Arguments are validated before anything runs, and service names may contain only letters, digits, dots, underscores, and hyphens.

Connecting Codex

Add a project-scoped entry to .codex/config.toml:

[mcp_servers.tdk]
command = "tdk"
args = ["mcp"]
cwd = "/absolute/path/to/your/tdk-project"
Enter fullscreen mode Exit fullscreen mode

The cwd must be the folder that contains .tdk/project.json. The server looks for the project there.

Connecting Claude Code

Claude Code connects the same way: the command is tdk, the argument is mcp, and the working directory is the project. The agent tooling guide has the setup steps for both clients.

How an agent should use it

The loop that works is short:

  1. Call doctor. If canUp is false, stop and report why.
  2. Call up, optionally limited to named services.
  3. Call status repeatedly until readiness.ready is true, or until failures appear.
  4. If a service fails, call logs for that service with a small tail.
  5. Call down when the work is finished.

up returns before the stack is ready, because a build can take longer than a single tool call. The polling in step 3 is what gives the agent a real finish line.

What to avoid

  • Do not expose the server to a network. It runs over standard input and output on your machine.
  • Do not let the agent stop or reset shared infrastructure without a person approving it.
  • Do not treat a successful up as proof the system works. Check status.

Summary

The MCP server lets an agent start, check, and stop the local stack through structured tools. Connect it from the project folder, give the agent the start-poll-report loop, and keep destructive actions with a person.

Top comments (0)