MCP Server

MCP Server

Built-in Model Context Protocol server. Exposes strut operations as callable tools so AI agents (Claude, Cursor, Kiro, and others) can inspect and operate your stacks directly, without you copy-pasting command output into chat.

Since: v0.33.0

Quick Reference

strut mcp install                     # interactive editor picker
strut mcp install --host cursor       # install for a specific editor
strut mcp serve                       # start the server manually (stdio)

Most of the time you only run strut mcp install once per project — your editor starts the server itself from then on.

Installing

strut mcp

Usage: strut mcp <command>

Commands:
  serve     Start MCP server on stdio (for IDE integration)
  install   Write MCP configuration for your IDE

strut mcp install uses agent-add (via npx) to write the right config for whichever editor you pick, falling back to a manual Kiro-only config (via jq) if npx isn't available:

strut mcp install --host cursor
strut mcp install --host claude-code
strut mcp install --host kiro
strut mcp install --host windsurf
strut mcp install --host github-copilot
strut mcp install --host gemini
strut mcp install --host codex
strut mcp install --host augment
strut mcp install --host roo-code

Omit --host for an interactive picker. See agent-add's host compatibility table for the full, current list — it covers more editors than strut has explicit examples for above.

Requires npx (preferred) or jq (Kiro-only fallback). Neither is a hard strut dependency — strut mcp install just can't do anything without at least one of them.

Starting the Server Manually

strut mcp serve

Reads JSON-RPC 2.0 messages from stdin, dispatches to tool handlers, writes responses to stdout — this is what your editor actually launches under the hood once it's configured via strut mcp install. You normally never run this by hand; it's documented here mainly so strut mcp install --host <unlisted-editor> has something concrete to point at if you're wiring up a tool agent-add doesn't know about yet.

Requires jq.

Tools Exposed

Every tool operates on the current project (wherever the MCP client's working directory resolves strut.conf from — same discovery strut's CLI itself uses).

Read-only

Tool	Description	Required args
strut_list	List all stacks in the project	—
strut_status	Container status for a stack	stack
strut_health	Run health checks for a stack	stack (env optional, default prod)
strut_logs	Recent logs for a service	stack (service, lines optional, default 50 lines)
strut_fleet_status	Git sync state across all topology hosts	—
strut_drift_detect	Detect configuration drift for a stack	stack
strut_drift_images	Check for stale container image digests	stack
strut_diff	Preview pending changes vs VPS	stack
strut_backup_health	Backup health scores for a stack	stack

Write (agent should confirm before calling)

Tool	Description	Required args
strut_deploy	Deploy/release a stack to VPS	stack (env optional, default prod)
strut_backup	Create a backup for a stack	stack (target optional, default all — one of postgres, neo4j, mysql, sqlite, all)
strut_stop	Stop containers for a stack	stack
strut_sync	Bring a host checkout in sync with origin	host (topology alias)

The write tools don't have their own separate confirmation flow inside the MCP server — they run immediately when called, exactly like the underlying strut command would. Whether the agent asks you before invoking a write tool depends on the client's own tool-approval settings, not on strut. If you want a write tool disabled entirely for a given editor, most MCP clients let you scope tool permissions per-server in their own settings.

How It Works

MCP client (Claude, Cursor, ...)
  │  JSON-RPC over stdio
  ▼
strut mcp serve
  │  dispatches method (initialize, tools/list, tools/call, ping)
  ▼
lib/mcp/tools.sh
  │  shells out to the real `strut` binary for the requested operation
  ▼
strut <stack> <command> --json

Tool calls are thin wrappers around the same strut <stack> <command> invocations you'd run yourself — there's no separate code path, so anything the CLI can do, the MCP server can expose without drift between the two.

Troubleshooting

Server doesn't respond / editor shows a connection error — confirm jq is installed (strut mcp serve requires it) and that your editor's MCP config points at a strut binary actually on PATH. Check what got written:

cat .kiro/settings/mcp.json   # or wherever your editor stores MCP server configs

strut mcp install falls back to the Kiro-only path unexpectedly — usually means npx couldn't be resolved. If you use nvm with lazy shell loading, this is a known gap strut works around (see the resolve_npx_bin note in Contributing) — if it still fails, running strut mcp install from a shell where node -v/npx -v already work directly should resolve it.

A tool call returns an error instead of expected output — the MCP server surfaces whatever the underlying strut command printed on failure (stack not found, VPS unreachable, etc.) — same troubleshooting as running that command directly. See Debugging.

Related

• Agent Steering — the complementary integration: installs strut's own operational context into your agent, rather than exposing strut to your agent
• CLI Reference — every command the MCP tools shell out to
• Debugging — troubleshooting the underlying commands MCP tools wrap