DCC REST Gateway — Agent Control Plane (No MCP)

This skill teaches any AI agent to drive DCC software through the DCC-MCP gateway HTTP API only. You do not need MCP tools/list, call_tool, resources/read, or Streamable HTTP — only curl (or any HTTP client) against the elected gateway (default port 9765).

Agent-facing gateway REST routes return compact TOON by default. The examples in this skill request Accept: application/json so shell agents can keep using plain JSON tooling; remove that header when the caller can decode TOON.

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

Full contract: docs/guide/rest-api-surface.md.

---

CRITICAL RULES (read first)

| Situation | You MUST | |-----------|----------| | Starting any DCC task | Run instance inventory (below) before search / call | | GET /v1/instances → total == 0 | STOP — do not call POST /v1/search or POST /v1/call | | Gateway unreachable (healthz fails) | STOP — explain; ask user permission before troubleshooting | | User has not agreed to setup | FORBID pip install, editing env files, launching GUI apps, writing configs | | User approved setup | Follow references/ZERO_INSTANCES.md; poll instances after each step | | After DCC crash/restart | Re-run inventory — instance_id and tool_slug values change |

---

Configuration

| Variable | Default | Meaning | |----------|---------|---------| | DCC_MCP_GATEWAY_URL | http://127.0.0.1:9765 | Gateway root (no trailing slash required) |

Set in the shell or OpenClaw env before running commands:

export DCC_MCP_GATEWAY_URL="${DCC_MCP_GATEWAY_URL:-http://127.0.0.1:9765}"
GATEWAY="$DCC_MCP_GATEWAY_URL"

Quick probe (cross-platform helper — stdlib only, no curl required):

# Linux / macOS
python3 scripts/check_gateway.py

# Windows (cmd or PowerShell)
py -3 scripts\check_gateway.py
# PowerShell wrapper:
pwsh scripts/check_gateway.ps1

# Optional: bash scripts/check_gateway.sh

Flags: --gateway URL, --pretty for indented JSON.

---

Step 0 — Mandatory instance inventory

Run every time you begin work or after the user starts/stops a DCC host:

GATEWAY="${DCC_MCP_GATEWAY_URL:-http://127.0.0.1:9765}"

curl -sf "$GATEWAY/v1/healthz" || echo "GATEWAY_UNREACHABLE"
curl -s  "$GATEWAY/v1/readyz"
curl -s  "$GATEWAY/v1/instances"
curl -s  "$GATEWAY/v1/context"    # optional summary

Interpret GET /v1/instances

Response shape:

{
  "total": 2,
  "instances": [
    {
      "instance_id": "full-uuid",
      "dcc_type": "maya",
      "status": "available",
      "stale": false,
      "display_name": "...",
      "scene": "...",
      "port": 8765,
      "mcp_url": "http://127.0.0.1:8765/mcp"
    }
  ]
}

Report to the user:

1. total — how many registry rows exist (routable targets when not stale).
2. Count by dcc_type — e.g. maya: 1, blender: 1.
3. Per row: instance_id, status, stale (ignore or warn on stale: true).
4. From GET /v1/context (optional): live_instance_count, loaded_skill_count, action_count.

Save one target instance_id per DCC you will use — pass it to POST /v1/search as instance_id (full UUID or unique ≥4-char prefix).

If total == 0

1. Tell the user: gateway may be up but no DCC has registered yet.
2. Do not call search, describe, or call (they fail or return empty).
3. Ask explicitly: "May I guide you through starting a DCC adapter for <product>?"
4. Only after yes → open references/ZERO_INSTANCES.md.
5. After each user action, re-run GET /v1/instances until total >= 1.

---

Step 1 — Discover tools (POST /v1/search)

Only when total >= 1 and rows are not stale.

curl -s -X POST "$GATEWAY/v1/search" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "sphere",
    "dcc_type": "maya",
    "instance_id": "<from-inventory>",
    "limit": 20
  }'

Copy hits[].tool_slug verbatim — format: <dcc>.<id8>.<backend_tool> (e.g. maya.a1b2c3d4.maya_primitives__create_sphere). Never hand-build slugs.

---

Step 2 — Inspect schema (POST /v1/describe)

curl -s -X POST "$GATEWAY/v1/describe" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"tool_slug": "<from-search>", "include_schema": true}'

Read tool.inputSchema and safety annotations before calling.

---

Step 3 — Invoke (POST /v1/call)

curl -s -X POST "$GATEWAY/v1/call" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_slug": "<from-search>",
    "arguments": { "radius": 2.0 }
  }'

• Tool-specific fields (code, file_path, radius, …) belong inside arguments, not at the top level.
• Multi-step (≤25): POST /v1/call_batch with calls[] and optional stop_on_error.

Path-style alternative when you already know dcc_type + instance_id:

POST /v1/dcc/{dcc_type}/instances/{instance_id}/call with body {"backend_tool": "...", "arguments": {...}}.

See references/REST_CHEATSHEET.md for the full endpoint list.

---

What this skill does NOT use

• MCP JSON-RPC (POST /mcp, tools/call, resources/read)
• Gateway MCP wrappers (including hidden call_tool) unless your host maps them to REST internally

REST and MCP share the same backend; this skill is for agents that only have HTTP.