Dcc Rest Gateway

Control live DCC hosts (Maya, Blender, Houdini, Photoshop, 3ds Max, and others) through the DCC-MCP gateway REST API only — no MCP client required. For any agent host (OpenClaw, ClawHub, Cursor, Claude, custom HTTP clients): inventory online instances, obtain user consent before setup when none are registered, then search, describe, and call tools via POST /v1/*.

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:

bash

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):

bash

# 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:

bash

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:

json

{
  "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.

bash

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)

bash

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)

bash

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.