MCP Quickstart — drive IDSDL from an AI agent

Beyond the Python API, the repo ships an MCP (Model Context Protocol) server that exposes the whole pipeline — planning, knowledge retrieval, asset search, program linting, phased builds, and rendering — as 28 tools an AI agent can call. This is the fastest way to use InteriorAgent: you describe the room you want in plain language, and the agent plans, writes, and builds the scene program for you.

Connect from Claude Code

Nothing to configure: the repo contains a .mcp.json that registers the server. From the repo root (with the installation done):

export OPENAI_API_KEY="sk-..."
claude        # open Claude Code in the repo root

Approve the interioragent MCP server when prompted, then just ask:

build me a cozy reading nook with a fireplace and a leather armchair

Connect from Claude Desktop (or any MCP client)

Point the client at the launch script with the repo as working directory:

{
  "mcpServers": {
    "interioragent": {
      "command": "/path/to/interioragent/tools/interioragent_mcp.sh",
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}

The launcher resolves the interioragent conda environment automatically (any of the common install locations, an active $CONDA_PREFIX, or an explicit IDSDL_PYTHON), and fails with an actionable message if the environment is missing.

The guided flow

The headline tool is the guided flow: a gated pipeline that walks the agent from a prompt to a judged, converged .blend, consulting the knowledge library of 55+ worked example scenes at every step:

1. PLAN — turn the prompt into a design target
2. RETRIEVE — reason over the knowledge catalog (matched worked examples + recipes)
3. AUDIT ASSETS — eyeball retrieved assets before placing anything
4. AUTHOR — write the phase-gated scene program
5. BUILD PHASE 1 — verify the floor layout (~1 min)
6. BUILD PHASE 2 — dress the surfaces
7. BUILD PHASE 3 — walls, lighting, mood + converge
8. JUDGE — score the result against the plan

Each gate validates mechanically where possible (lint, build reports, VLM feedback) before the flow advances; the agent can pass a gate deliberately with flow_override — gates guide, they don’t imprison. A teach=True mode appends a ninth WRITE BACK gate that distills the finished scene into a new worked example, growing the knowledge base.

Key tools (call howto for the full catalog):

Tool	What it does
howto	Orientation: the toolbox, the workflow, and the house rules.
flow_start / flow_status / flow_advance	Run the guided flow above.
plan, plan_refine	Design targets: palette, layout idea, hero pieces.
retrieve, candidates, inspect, pin	Asset search, candidate audit, durable pins.
lint_program	Static checks on a scene program before building it.
run_scene	Build a program (phase-gated) and report warnings + renders.
show, gallery	Render views of the current build.
shop_search, shop_run, shop_apply	Acquire missing assets (Sketchfab / Meshy).
ingest_glbs, pool_add	Ingest your own GLB files into the retrieval pool.

One-command automatic mode

Prefer no agent in the loop? The same pipeline runs fully automatically:

python main.py "a warm scandinavian bedroom with a reading corner"

Verify

python3 tools/mcp_smoke.py             # handshake + tools/list + howto
python3 tools/mcp_smoke.py --retrieve  # plus a real asset retrieval

On failure the smoke test prints the server’s stderr, which names exactly what is missing (conda env, mcp package, datasets, key).

---

Next: the knowledge base the guided flow draws on — and a dozen rendered builds — is on the Worked Examples page.