Kranz MCP lets a coding agent observe and operate the same local project runtimes the TUI and CLI use, without starting a second stack.
Discover runtimes — list visible project runtimes (runtimes) and pick one per call.
Lifecycle control — up a project runtime, down one this session started, and start/stop/restart services.
Inspect state — status, health (with probe history), graph (dependency/prerequisite/ownership), and runs (bounded run catalog).
Ports — ports for declared/detected ports, port_inspect to identify any listener.
Logs — query bounded logs, clear buffers with logs_clear, and browse/delete runs via runs and run_delete.
Actions — action_list, action_info, action_run (typed params), action_result, action_cancel.
Planning & safety — plan resolves a start/stop/restart/action plan without executing; destructive calls use confirmation tokens/flags.
Watch changes — changes (cursor-based journal) and wait for ready/running/stopped/healthy/unhealthy conditions.
Diagnostics & config — doctor preflight checks and reload after editing configuration files.
Kranz starts, observes, and stops a local development stack from one terminal. It understands dependency order, readiness and liveness, process groups, runtime ports, logs, one-shot actions, and detached infrastructure whose life is not tied to a local PID.
Each project runtime is owned by a separate user-level supervisor; the TUI, CLI, and MCP connect to it as clients. There is no system service or shared control plane. Use it for the processes you would otherwise spread across terminal tabs, alongside Docker Compose when containers remain the right home for infrastructure.
Kranz exposes each runtime through three views:
TUI — the keyboard-first operator view for services, details, logs, lifecycle plans, actions, health history, and notifications;
CLI — the terminal and scripting view, including stable JSON results;
MCP — the coding-agent view over the same application operations.
They use the same supervisor. A service restarted by a command or coding agent changes immediately in the open TUI; none of these views starts a second stack.
Large workspaces can compose independently runnable repository configs through
exact includes, globs, or bounded discovery. File-local defaults and relative
paths stay isolated; ordered --override layers, final protected values,
stable service IDs, provenance, and safe pending reloads remain identical in
the TUI, CLI, and MCP.
Kranz MCP gives a coding agent the same services, actions, readiness, ports, bounded logs, and numbered run history visible in the TUI. It attaches to the existing runtimes instead of starting a second development stack.
Shared runtimes — TUI, CLI, and MCP converge on the supervisor of the project addressed by each call.
One view of the project — the same selectors, action runs, and logs.
Clear ownership — disconnecting an attached agent does not stop the stack.
Register the existing binary once, globally, as a stdio MCP server running
kranz mcp. It takes no project: the runtime is chosen per call, so one
registration covers every project, and connecting creates nothing.
See Coding agents and your live runtimes for ownership behavior and examples, and the MCP reference for the exact resource, tool, cursor, confirmation, and error contracts.
For Claude Code, the Kranz plugin bundles the MCP connection with the agent skill. After installing the binary, add this repository as a plugin marketplace and install the plugin:
claude plugin marketplace add kranz-org/kranz
claude plugin install kranz@kranzThe standalone agent skill remains available for Codex, OpenCode, and other clients that support Agent Skills. Keep the plugin's copy of the skill synchronized with this source when updating it.
Related MCP server: worktree-switcher
Install on macOS or Linux:
brew install kranz-org/tap/kranzOr with Go 1.26 or newer:
go install github.com/kranz-org/kranz/cmd/kranz@latestCreate a Procfile:
web: python3 -u -m http.server 8000 --bind 127.0.0.1
worker: while true; do date; sleep 2; doneRun kranz, press a to select everything, then s to start. Kranz discovers
the web listener automatically and shows both services' state and logs.
Already using a supported process-compose.yaml? Run kranz beside it. Use
native kranz.yaml when you need the complete lifecycle model.
The TUI is optional. Kranz includes a complete CLI for starting a project in the background, inspecting it from another terminal, acting on services, and returning stable JSON to scripts:
kranz init --from Procfile
kranz config check
kranz up -d
kranz status
kranz logs api --tail 20
kranz runs api
kranz logs api --run -1
kranz restart api
kranz downUse kranz --help to discover commands, kranz COMMAND --help for command
options, and --output json for the versioned machine-readable envelope. See
Working from the command line
for a complete session and the CLI reference
for every command, option, output contract, and exit code.
Dependency-aware startup and reverse-order shutdown
HTTP, TCP, and command readiness/liveness checks
Process recovery with backoff and restart limits
Managed and observe-only detached resources with start/stop/status/logs
Service actions and project action groups with timeout and confirmation
Typed action parameters shared by TUI, CLI, MCP, and prerequisites
Prerequisites that must succeed before a service starts
Runtime port discovery and ownership-aware conflict handling
Searchable, pinnable, timestamped logs in a keyboard and mouse TUI; selection controls share the footer with right-aligned action status, and clearing a selection keeps the position reached while scrolling
Your own log tools: shell pipelines for in-panel formatting, or a terminal viewer for selected runs
In-place switching between live local runtimes with per-runtime TUI state
Bounded per-service and per-action run history with provenance, exact output retention state, navigation, deletion, and export
Procfile, native YAML, and conservative Process Compose loading
Detected configuration changes with explicit reload and last-known-good fallback
Exact CLI filters, bounded live watch, stable JSON, and Docker-style row templates for automation
Draft-based configuration authoring with editable services, actions, appearance, and a final diff before writing
The documentation source lives in docs/ and is deployed to
kranz-org.github.io/kranz/ from main.
make verify
make lint
npm install
npm run docs:devRelease instructions are in docs/RELEASING.md.
Explicitly cancel a currently running non-interactive action.
Inputs: action (required), runtime. Returns: data, error, session, generation, +1 more
Describe one exact OWNER/ACTION.
Inputs: action (required), runtime. Returns: data, error, session, generation, +1 more
List actions, optionally filtered by exact owner.
Inputs: owner, runtime. Returns: data, error, session, generation, +1 more
Return a current or retained action result by absolute or negative-relative run.
Inputs: action (required), run, runtime. Returns: data, error, session, generation, +1 more
Run one non-interactive action. Pass a typed params object for a parameterized action; action_info returns its advisory schema. MCP request cancellation does not cancel the action.
Inputs: action (required), params, runtime, confirmation_token. Returns: data, error, session, generation, +1 more
Return what changed in the runtime after a cursor: service and action transitions, detected-port changes, and configuration reloads.
Inputs: kinds, limit, since, runtime, +2 more. Returns: data, error, session, generation, +1 more
Run project preflight checks: configuration diagnostics, dependency cycles, service directories, env files, shells, and declared ports.
Inputs: runtime. Returns: data, error, session, generation, +1 more
Stop a runtime this MCP session started with up. Runtimes started by a person are never stopped from here.
Inputs: runtime (required), confirm. Returns: data, error, session, generation, +1 more
Return the declared dependency, prerequisite, and ownership graph with live service state folded in.
Inputs: runtime. Returns: data, error, session, generation, +1 more
Return readiness and liveness probe state, including the probed target and its last error, with recorded health history.
Inputs: history, runtime, selectors. Returns: data, error, session, generation, +1 more
Query bounded normalized service and action logs.
Inputs: run, runs, tail, since, +5 more. Returns: data, error, session, generation, +1 more
Clear explicitly selected bounded service/action log buffers.
Inputs: selectors (required), runtime, with_actions. Returns: data, error, session, generation, +1 more
Resolve a versioned start, stop, restart, or action plan without executing it. A parameterized action takes the same typed params object action_run takes, and the plan carries the exact command it would run.
Inputs: operation (required), action, params, runtime, +2 more. Returns: data, error, session, generation, +1 more
Identify the current listener on explicit port numbers, including processes Kranz does not manage.
Inputs: ports (required), runtime. Returns: data, error, session, generation, +1 more
Inspect declared and detected service ports without changing their owners.
Inputs: runtime, selectors. Returns: data, error, session, generation, +1 more
Re-read the configuration from disk and reconcile it into the running services. Use it after editing a Kranz configuration file.
Inputs: force, runtime. Returns: data, error, session, generation, +1 more
Restart selected services and affected dependents using the resolved application plan.
Inputs: selectors (required), runtime, confirmation_token. Returns: data, error, session, generation, +1 more
Delete one completed absolute service or action run and its retained output after explicit confirmation.
Inputs: run (required), target (required), confirm, runtime. Returns: data, error, session, generation, +1 more
Return the bounded service and action run catalog with provenance and output retention state.
Inputs: runtime. Returns: data, error, session, generation, +1 more
List the Kranz project runtimes visible to this user. Read this first when a call answers runtime_required or runtime_not_found: every entry can be passed back as the runtime argument.
Inputs: no named parameters. Returns: data, error, session, generation, +1 more
Start selected services using the resolved application plan.
Inputs: selectors (required), runtime, confirmation_token, include_dependencies. Returns: data, error, session, generation, +1 more
Return live status for selected services, including the structured cause of a state whose reason is not the state itself.
Inputs: runtime, selectors. Returns: data, error, session, generation, +1 more
Stop selected services and affected dependents using the resolved application plan.
Inputs: selectors (required), runtime, confirmation_token. Returns: data, error, session, generation, +1 more
Start the runtime of a project that has none, without starting any service. This creates a background process that outlives this MCP session and stays in kranz ps until someone stops it; use it only when asked to bring a project up.
Inputs: confirm, directory. Returns: data, error, session, generation, +1 more
Wait cancellably for ready, running, stopped, healthy, or unhealthy.
Inputs: condition (required), selectors (required), runtime, timeout. Returns: data, error, session, generation, +1 more
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 25 tools
Each tool targets a distinct operational concept (runtime lifecycle vs service lifecycle vs actions vs logs), and descriptions clarify edge cases like up/down vs start/stop. Some adjacent tools (ports vs port_inspect, status vs health vs wait, runs vs action_result) could be initially confused but are distinguishable on reading.
Names mix bare nouns (runtimes, status, logs), bare verbs (up, start, reload), and snake_case with resource prefixes (action_list, run_delete, logs_clear). The action_* family is consistent, but overall there is no single predictable verb_noun pattern. Still readable.
25 tools is heavy for an MCP surface, but the domain spans runtime, services, actions, logs, ports, health, and configuration, so most tools correspond to real operations. Borderline over-scoped rather than redundant.
Operational lifecycle is well covered: runtime up/down, service start/stop/restart/status/health/wait, action run/cancel/result, logs query/clear, plan, graph, ports, doctor, reload, and run deletion. Missing are config-editing operations and possibly service-level env/secret management, but these may be out of scope.
Develop, manage, and debug Railway projects, services, and deployments from within agents.
Read a project's prompts, logs and agents, and send new work to the agent on your own machines.
Connect AI agents to shared Spaces for context, sourced work, tasks, and runs.
Connect agents to 6DuckLearn memory, approvals, and runtime control.
