DCC CLI Gateway — Agent Control Plane

Agents use dcc-mcp-cli; IDE users keep native MCP. One skill for shell-capable agent hosts — no MCP connector required.

Use this skill when an agent or headless CLI host can run shell commands and should control DCC-MCP through dcc-mcp-cli. The CLI uses local FileRegistry + direct per-DCC MCP in the built-in local profile, and gateway REST (/v1/search, /v1/describe, /v1/call) for named remote profiles.

The CLI returns JSON by default. The bundled Python fallback is gateway-REST only and sends Accept: application/json because the gateway REST API itself now defaults to compact TOON for agent-facing routes.

Agent Path vs IDE Path

DCC-MCP supports two integration paths. Pick the one that matches how the user works — do not force IDE users onto the CLI, and do not ask agents to configure MCP when they can run shell.

| Dimension | Agent path (this skill) | IDE path (native MCP) | |-----------|----------------------------|---------------------------| | Who | OpenClaw, Hermes, Codex CLI, CI bots, custom agent runtimes, any host with shell | Cursor, Claude Desktop, VS Code MCP, other MCP-native clients | | Transport | dcc-mcp-cli → local MCP or remote gateway REST | MCP Streamable HTTP → gateway /mcp | | Discovery surface | search → describe → call via CLI or bundled Python helper | Gateway MCP tools: search, describe, load_skill, call | | Setup | Install this skill; optional dcc-mcp-cli on PATH or --ensure-cli with consent | Add gateway URL to IDE MCP settings (see repo docs/guide/*) | | When to choose | Host has no MCP connector, runs headless, or studio wants one forkable skill | User already works inside an IDE with MCP configured | | Resources / prompts | Not covered here; use REST /v1/context or IDE MCP if needed | resources/read, prompts/get, SSE subscribe via MCP |

Decision rules for agents loading this skill:

Use this skill (CLI path) when the host can execute shell and the task is DCC control (search → describe → call). This is the default for agents.
Do not use this skill when the user is in Cursor / Claude Desktop / VS Code with gateway MCP already configured — point them to their IDE MCP workflow instead.
Do not mix paths in one turn — pick CLI+REST or MCP for the whole task, not both.
Zero instances — stop, explain, ask consent before bootstrap; see references/ZERO_INSTANCES_CLI.md.

Internal studios can fork this skill once and reuse the same CLI+REST workflow across agents without maintaining per-host MCP server lists.

Gateway Profiles And Local-First Inventory

dcc-mcp-cli has a built-in local profile. In local mode, agent-control commands first ensure the machine-wide loopback gateway is healthy, then list reads the core default FileRegistry directly, and search, describe, load-skill, call, wait-ready, and guarded stop-instance talk to the selected local DCC instance's advertised MCP/readyz/safe-stop endpoints. Remote machines are selected through named gateway profiles:

Treat list as inventory plus diagnostics, not proof that a row is callable. It intentionally keeps live booting / dispatch_status=unavailable sidecar rows visible. Local search, describe, load-skill, call, and reload-skills route only to rows ready for local CLI control. Per-DCC sidecar rows become local MCP routes once they report dispatch_status=ready; before that, they remain visible for diagnostics. Use wait-ready or doctor when a listed instance is still booting.

dcc-mcp-cli gateway register https://workstation.example:19293 --name pcA
dcc-mcp-cli gateway list
dcc-mcp-cli gateway set pcA
dcc-mcp-cli gateway set local
dcc-mcp-cli list --gateway pcA

Use --gateway <name> to override the current profile for one command. --base-url / DCC_MCP_BASE_URL remain direct endpoint overrides for legacy scripts and smoke checks.

Agent-control commands (list, search, describe, load-skill, call, wait-ready, reload-skills, and stop-instance) and endpoint-level commands such as health, update, and smoke without an explicit --url auto-ensure loopback HTTP gateway targets. File-only commands and explicit lifecycle commands do not auto-start the gateway. When startup state is unclear, run dcc-mcp-cli doctor before troubleshooting adapters. It reports profile config/current selection, the registry directory and local inventory, direct-control readiness counts, gateway daemon status, and server binary path/source/version without launching or downloading anything. When list shows local rows, prefer direct_control.recommended_next_action over guessing from status text; sidecar rows are local tool-call routes only after direct_control.ready=true. If direct_control.ready=false, inspect direct_control.diagnostics.failure_stage, failure_reason, host_rpc_*, and any diagnostics.logs.* paths before retrying. doctor summarizes the same not-ready rows under local.inventory.direct_control.not_ready_instances.

What auto-ensure does

Probe GET /health on the gateway port.
If healthy -> continue.
If unreachable -> acquire a launch lock, spawn the gateway daemon in the background, poll until healthy, then release the lock.
Run the original command; local control commands still use FileRegistry and direct per-DCC MCP after the gateway lifecycle check succeeds.

CLI usage

# Local inventory - auto-ensures the loopback gateway first
dcc-mcp-cli list

# Startup diagnostics - no service launch or download
dcc-mcp-cli doctor

# Gateway health check - auto-starts loopback gateway if needed
dcc-mcp-cli health

# Disable auto-start for one command
dcc-mcp-cli --no-auto-gateway list

# Explicit daemon lifecycle
dcc-mcp-cli gateway daemon start
dcc-mcp-cli gateway daemon status
dcc-mcp-cli gateway daemon restart

# Set longer auto-start wait timeout
dcc-mcp-cli --auto-gateway-timeout-secs 30 health

gateway daemon start and gateway daemon restart are the durable operator paths: their start phase passes --gateway-idle-timeout-secs 0 by default so an explicitly managed local daemon does not exit just because no DCC backend is registered yet.

Explicit ensure result format

{
  "host": "127.0.0.1",
  "port": 9765,
  "already_running": true,
  "pid": 12345
}

already_running: true -> gateway was already up; proceed to endpoint-level gateway commands.
already_running: false -> gateway was just started by this call (includes pid).

If auto-ensure fails

| Symptom | Likely cause | Action | |---------|-------------|--------| | Timeout after --auto-gateway-timeout-secs | Gateway binary missing or port conflict | Ask user to install dcc-mcp-core or check port availability | | Lock contention | Concurrent launch race | Retry after a short delay | | Port 0 rejected | Invalid config | Verify DCC_MCP_GATEWAY_PORT or --port is non-zero | | Remote profile or DCC_MCP_BASE_URL unreachable | Auto-start only applies to local loopback HTTP URLs | Report the remote gateway as unreachable |

Python fallback note

The Python fallback (dcc_gateway.py) does NOT include a gateway ensure command because the ensure flow spawns a subprocess daemon - a capability specific to the compiled CLI. When the CLI binary is unavailable, skip to dcc_gateway.py health directly. If health fails, report the gateway as unreachable and ask the user to start a gateway manually or install dcc-mcp-cli.

Connection Order

Use dcc-mcp-cli list for local inventory, or dcc-mcp-cli list --gateway <name> for a remote profile.
Use dcc-mcp-cli for all subsequent commands when it is on PATH.
If missing, ask user permission, then download dcc-mcp-cli from GitHub Releases.
If the download fails, use the bundled Python stdlib REST fallback.

Install via OpenClaw/ClawHub, or point your agent at this SKILL.md after cloning dcc-mcp-core/skills/dcc-cli-gateway/.

Critical Rules

| Situation | You MUST | |-----------|----------| | Starting any local DCC task | Run dcc-mcp-cli list; it ensures the local gateway, then reads the local FileRegistry | | Startup state is ambiguous | Run dcc-mcp-cli doctor; inspect selected profile, registry dir, local inventory, direct-control readiness counts, daemon status, and server binary diagnostics | | Starting any remote DCC task | Select or override a profile with dcc-mcp-cli gateway set <name> or dcc-mcp-cli list --gateway <name> | | dcc-mcp-cli missing | Ask permission before --ensure-cli; fallback Python REST is allowed if download fails | | CLI auto-ensure fails | Stop; explain the result; do not run agent-control or gateway endpoint commands until the gateway is reachable | | Inventory returns total == 0 | Stop; do not run search, describe, or call | | Remote gateway unreachable | Stop; explain; ask user permission before troubleshooting | | User has not agreed to setup | Do not install packages, edit env files, launch GUI apps, or write configs | | User approved setup | Follow references/ZERO_INSTANCES_CLI.md | | After DCC crash/restart | Re-run list and search; old slugs may be invalid |

Configuration

dcc-mcp-cli stores remote gateway profiles under ~/.dcc-mcp/gateway-profiles.json. The Python helper still reads a gateway URL from DCC_MCP_BASE_URL.

dcc-mcp-cli list
dcc-mcp-cli gateway register https://workstation.example:19293 --name pcA
dcc-mcp-cli gateway list
dcc-mcp-cli list --gateway pcA
python scripts/dcc_gateway.py --base-url http://127.0.0.1:9765 health

For a one-off command:

python scripts/dcc_gateway.py --base-url http://127.0.0.1:9765 health

Quick probe helper:

python3 scripts/check_cli.py
py -3 scripts\check_cli.py

Flags: --base-url URL, --cli dcc-mcp-cli, --ensure-cli, --install-dir DIR, --pretty.

When the user approves downloading the CLI:

# Linux / macOS
python3 scripts/dcc_gateway.py --ensure-cli list
vx python scripts/dcc_gateway.py --ensure-cli list

# Windows
py -3 scripts\dcc_gateway.py --ensure-cli list
vx python scripts\dcc_gateway.py --ensure-cli list

Release assets are selected by platform:

| Platform | Asset | |----------|-------| | Windows x86_64 | dcc-mcp-cli-windows-x86_64.exe | | Linux x86_64 | dcc-mcp-cli-linux-x86_64 | | macOS Intel/Apple Silicon | dcc-mcp-cli-macos-universal2 |

If Python is not easy to locate, install vx first and run the helper through vx python:

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/loonghao/vx/main/install.sh | bash

# Windows PowerShell
powershell -c "irm https://raw.githubusercontent.com/loonghao/vx/main/install.ps1 | iex"

Step 0 — Local Inventory First

Run this as the very first step every time you begin local work or after a DCC adapter restarts:

# Local FileRegistry inventory
dcc-mcp-cli list

# No-launch startup diagnostics when state is unclear
dcc-mcp-cli doctor

# Optional gateway health check
dcc-mcp-cli health

Interpret the result:

list.total > 0 -> inspect status/dispatch metadata. Local search, describe, load-skill, call, and reload-skills only route to rows ready for local CLI control; use wait-ready or doctor for live-but-booting rows, including sidecars that have not reached dispatch_status=ready.
doctor.profile.selected.mode / doctor.local.registry_dir -> confirms which local/remote mode and registry path the CLI is using before adapter setup.
health.status == "ok" -> gateway is up when you need gateway endpoint/admin/update workflows.
Error / timeout -> stop; explain the failure to the user. For remote profiles, the CLI cannot auto-start the gateway.

Step 1 — Mandatory Instance Inventory

Run this every time the user starts/stops a DCC host:

# CLI (primary)
dcc-mcp-cli list
dcc-mcp-cli health

# Python fallback (when CLI is unavailable)
python scripts/dcc_gateway.py health
python scripts/dcc_gateway.py list

Interpret dcc-mcp-cli list:

{
  "total": 1,
  "instances": [
    {
      "instance_id": "full-uuid",
      "instance_short": "a1b2c3d4",
      "dcc_type": "maya",
      "status": "available",
      "stale": false,
      "mcp_url": "http://127.0.0.1:8765/mcp"
    }
  ]
}

Report to the user:

total
Count by dcc_type
Any stale: true rows
The target instance_id or instance_short you will use

If total == 0, stop and ask whether the user wants setup guidance for the target DCC. Continue only after explicit approval.

Step 2 — Search Tools

Only run this when inventory shows at least one non-stale target:

# CLI (primary)
dcc-mcp-cli search --query sphere --dcc-type maya --limit 20

# Python fallback
python scripts/dcc_gateway.py search --query sphere --dcc-type maya --limit 20

Copy the returned slug exactly. Local and gateway slugs use the same agent-facing shape:

maya.a1b2c3d4.maya_primitives__create_sphere

Never hand-build slugs.

Step 3 — Describe Schema

# CLI (primary)
dcc-mcp-cli describe maya.a1b2c3d4.maya_primitives__create_sphere

# Python fallback
python scripts/dcc_gateway.py describe maya.a1b2c3d4.maya_primitives__create_sphere

Read tool.inputSchema and safety annotations before calling.

Step 4 — Call a Tool

# CLI (primary)
dcc-mcp-cli call maya.a1b2c3d4.maya_primitives__create_sphere \
  --json '{"radius":2.0}'

# Python fallback
python scripts/dcc_gateway.py call maya.a1b2c3d4.maya_primitives__create_sphere \
  --json '{"radius":2.0}'

Tool-specific fields (code, file_path, radius, and similar) belong inside the --json object. Do not pass them as top-level CLI flags unless the CLI adds an explicit first-class flag later.

See references/CLI_CHEATSHEET.md for command patterns and common errors.

Updates and Marketplace Maintenance

Use the gateway update manifest for binary checks:

# Check whether the local CLI has an update.
dcc-mcp-cli update check

# Check a server/instance version shown in the admin panel.
dcc-mcp-cli update check --binary dcc-mcp-server --current-version 0.18.16

# Stage a CLI binary update for the next CLI launch.
dcc-mcp-cli update apply

dcc-mcp-cli update apply only stages the CLI binary. To update a running server binary, run the server-side command in that server environment:

dcc-mcp-server update check
dcc-mcp-server update apply

Use marketplace commands for skills:

dcc-mcp-cli marketplace search --query rigging --dcc maya --limit 20
dcc-mcp-cli marketplace inspect <package_name>
dcc-mcp-cli marketplace install <package_name> --dcc maya
dcc-mcp-cli reload-skills --dcc-type maya
dcc-mcp-cli marketplace outdated --dcc maya
dcc-mcp-cli marketplace update <package_name> --dcc maya
dcc-mcp-cli reload-skills --dcc-type maya

After installing or updating skills, first run dcc-mcp-cli reload-skills --dcc-type <dcc> so running adapters re-scan the marketplace skill path. Then use dcc-mcp-cli load-skill for a live instance when the adapter has not auto-loaded the skill yet.

Use install for adapter plans, not marketplace skills:

dcc-mcp-cli install --dcc-type maya --version 2026
dcc-mcp-cli install --dcc-type maya --version 2026 --python "C:/Program Files/Autodesk/Maya2026/bin/mayapy.exe"
dcc-mcp-cli install --dcc-type maya --version 2026 --python "C:/Program Files/Autodesk/Maya2026/bin/mayapy.exe" --execute

Agents must ask before using --execute. The executor prompts for consent, rolls back completed steps if a later step fails, verifies pip packages with pip show, and verifies git/zip/path installs by checking their target path. Package install is not online registration: the DCC plugin or sidecar must start and remain alive before dcc-mcp-cli list shows an instance. Treat the install JSON next_steps array as the authoritative machine-readable follow-up sequence. If it includes read-install-instructions, read that adapter repository's raw install.md first; it owns host-specific setup. Then start/enable the host plugin, run doctor, confirm list, wait for readiness, search/call tools, and use marketplace search, inspect, install, then reload-skills for optional community skill packages.

If install_policy.auto_install_enabled is false, do not retry with --execute. Show the returned install_policy.prompt to the user and hand off to the named Pipeline TD / studio deployment path. Studios set this through DCC_MCP_INSTALL_DISABLED=1 and DCC_MCP_INSTALL_DISABLED_PROMPT.

What This Skill Does Not Use

Native MCP tools/list, tools/call, or resources/read on the agent host (IDE users should use MCP instead of this skill)
Raw curl workflows except when debugging the gateway itself
Direct Maya/Blender/Houdini scripting

The CLI is the default agent-facing control plane. The Python fallback uses the same gateway REST endpoints only when the CLI is unavailable after a download attempt fails. The gateway still serves MCP for IDE clients in parallel; choosing this skill does not replace or disable the IDE MCP path.