MCP Setup Guide

1. What is MCP

MCP (Model Context Protocol) is the standard protocol for AI agents to call external tools. Once connected, your coding agent gains a set of "AiArtEngine tools" and can drive the app through conversation:

Claude Code / Codex ──stdio(MCP)──▶ mcp-bridge.mjs ──HTTP──▶ AiArtEngine app (127.0.0.1 tool service)

• On startup the app serves a token-protected tool service on 127.0.0.1 and writes connection info to %APPDATA%/aiartengine/mcp.json (macOS / Linux paths below). The file persists across restarts and the token stays stable — configure clients once; you can also edit the token in the app under Settings → MCP.
• The bridge scripts/mcp-bridge.mjs is dependency-free: the agent client spawns it, and it translates the protocol and forwards calls.
• Communication stays on the loopback interface; everything except the health check requires the token.

2. Connect Claude Code in 3 steps (choose one of two)

Option A: stdio bridge (recommended)

1. Start the AiArtEngine desktop app.
2. Register the MCP server (the bridge lives in the repository — adjust the path):

   claude mcp add aiartengine -- node C:/path/to/ai-art-engine/scripts/mcp-bridge.mjs

   or write it into your MCP config file manually:

   {
     "mcpServers": {
       "aiartengine": {
         "command": "node",
         "args": ["C:/path/to/ai-art-engine/scripts/mcp-bridge.mjs"]
       }
     }
   }

3. Restart the agent session and the tools are ready. Other MCP-capable clients (Codex, Trae, …) use the same "command + args" configuration.

Option B: HTTP direct (no Node.js required)

Clients that support streamable HTTP can skip the bridge. The token lives in mcp.json (persisted):

claude mcp add --transport http aiartengine http://127.0.0.1:43110/mcp --header "Authorization: Bearer <token>"

Config template (.mcp.json)

.mcp.json is optional and must be created manually (nothing generates it for you) — create a text file named .mcp.json, fill in the template below, and place it in the root of the project where you run Claude Code. Commit it and your team gets it on clone.

stdio bridge variant (adjust the path):

{
  "mcpServers": {
    "aiartengine": {
      "command": "node",
      "args": ["C:/path/to/ai-art-engine/scripts/mcp-bridge.mjs"],
      "env": {
        "AIAE_MCP_CONFIG": "C:/Users/<you>/AppData/Roaming/aiartengine/mcp.json"
      }
    }
  }
}

HTTP direct variant (no Node.js required — token from the app-side mcp.json):

{
  "mcpServers": {
    "aiartengine": {
      "type": "http",
      "url": "http://127.0.0.1:43110/mcp",
      "headers": {
        "Authorization": "Bearer <token from the app-side mcp.json>"
      }
    }
  }
}

3. Tool reference

4. Example conversations

Once connected, just give natural-language instructions — the agent combines the tools:

• "List my recent projects and open the first one" → project_list + project_open
• "Plan a workflow from the shortDrama template and save it" → workflow_plan (presetId=shortDrama) + workflow_commit
• "Run the workflow I just created and report back" → task_run + task_status polling
• "Add a voice node under this image node and wire it" → graph_edit (node_upsert + edge_connect)
• "What nodes can this graph take? Which type packs icons?" → graph_node_types (typeId + ports + default params)
• "Icon #3 in the pack looks blurry — redraw just that one" → graph_icon_refine (cellKey + hint; writes back and re-packs)
• "Generate a 9:16 poster with my configured model" → models_list + generate_image

5. Configuration & environment

The bridge reads %APPDATA%/aiartengine/mcp.json by default (macOS: ~/Library/Application Support/aiartengine/; Linux: ~/.config/aiartengine/). To override:

The app tries ports 43110–43119 in order and skips occupied ones; the actual port is whatever mcp.json contains.

5.1 stdio bridge settings

Settings → MCP tool server → stdio bridge tab visualizes the bridge config — no env vars to hand-edit. You can set: the bridge command (default is still node + the in-repo scripts/mcp-bridge.mjs or the installer's bundled <install dir>/resources/mcp-bridge.mjs), the bridge port (default HTTP port the bridge listens on), the BLENDER_HOST / BLENDER_PORT passthrough for the Blender addon. Changes persist immediately; external agents just reconnect — no app restart needed.

5.2 Reverse bridge: let dsh (in-app chat panel) connect to stdio MCP servers

The "forward bridge" brings Claude Code and other external agents in via stdio bridge or HTTP. The reverse bridge goes the other way — the in-app ◈ AI chat panel (DeepSeek Harness / dsh) can also register and consume any external stdio MCP server (not limited to its own /mcp endpoint).

Typical scenario: the Blender addon or any other stdio-only MCP server no longer needs to expose a separate socket port; once dsh registers a claude mcp add --transport stdio ...-style command, "use Blender to assemble this and screenshot it" in the conversation drives the addon directly. Configuration lives in the same settings panel — MCP tool server → stdio bridge tab — and supports multiple external stdio servers (each with name / command / working dir / env); they share the same store as the Blender stdio bridge.

Protocol details:

• The reverse bridge forks a stdio subprocess inside the dsh process, translates MCP frames and reuses the existing mcp-client instance — no separate bridge process
• Protocol errors and subprocess crashes share the same audit log (<userData>/logs/mcp-audit.jsonl) as the forward bridge
• Local only, with token auth; external stdio servers do not automatically gain write access to the app's /mcp endpoint
• Ask / Plan modes also keep reverse-bridge tools read-only — they aren't a side door around panel mode

6. Security & limitations

• The service listens on 127.0.0.1 only, with token auth; file access is confined to the project root (the single exception is asset_import, which reads absolute paths you pass in and copies them into the project); secrets are never exposed.
• Concurrency gate: generate_image / generate_speech / decide / workflow_plan run at most 3 concurrently (AIAE_MCP_GEN_LIMIT tunable); excess queue is rejected with a friendly error.
• Audit trail: every tool call is appended to <userData>/logs/mcp-audit.jsonl (args truncated, 5MB rotation) so generation and writes can be audited.
• graph_edit / graph_icon_refine refuse graphs that are currently open in an editor to avoid clobbering in-memory state.
• workflow_plan runs an LLM and may take tens of seconds; generate_video / generate_model3d are async — track them with video_job_*.
• Two connection options: the stdio bridge (bundled in installers at <install dir>/resources/mcp-bridge.mjs; for development use the in-repo scripts/mcp-bridge.mjs, Node.js 18+ required) or HTTP direct (no Node.js needed).

7. Blender tools (advanced)

These tools are not part of the main /mcp toolset — they live on a sibling endpoint /mcp/blender on the same service (enabled by default in Settings → MCP → Blender tools; the endpoint returns 403 if you turn it off, and the main toolset is unaffected).

Let AI drive Blender directly — build scenes, write bpy code, screenshot for self-check, export GLB / GLTF / FBX into your project. The app makes an outbound socket to the addon's localhost:9876 — no uv, no Python subprocess, no Blender config tweaks.

Prerequisites

• Blender is running with an MCP addon enabled (pick the matching type in Settings → MCP → Blender tools — the two wire protocols are incompatible; mismatch shows up as a connect timeout or "connection reset"):
  • Community (default): blender-mcp's addon.py, installed under Edit → Preferences → Add-ons
  • Official: the Blender Lab "MCP Server" extension on the Blender Extensions platform — start the service in the extension's preferences
• Both addons listen on 9876 by default; if you change it, update the port in Settings.
• External agents need a second MCP server registered to reach these tools (<token> from the app-side mcp.json):

  claude mcp add --transport http blender http://127.0.0.1:43110/mcp/blender --header "Authorization: Bearer <token>"

  The in-app ◈ AI chat panel wires it automatically (dsh registers a second mcp-client instance), so just say "use Blender …" in the conversation.

Tool reference

Tool names, schemas and outputs are identical across both addons — the model side doesn't care which is running:

Typical loop

get_scene_info            Inspect state
   ↓
execute_blender_code      Write bpy: model / material / camera
   ↓
get_viewport_screenshot   Self-check the viewport (multimodal client sees the image)
   ↓
export_scene              Export GLB / GLTF / FBX …
   ↓
asset_import              Land it in the asset library

Safety rails

• execute_blender_code no longer applies a lexical code guard: full Python / bpy is allowed (including class / lambda / open, etc.). The real write backstop is the §6 mode constraint — Ask / Plan make the whole group read-only, and write calls are rejected.
• Screenshots go through a one-shot temp file: get_viewport_screenshot writes to a system temp file the app reads and deletes immediately; the image is returned only in-band to multimodal clients and never touches the project or the audit log.
• Mode is bound to the request, not the client: the Blender endpoint shares the service's token; Ask / Plan flow through X-AIArt-Mode / X-AIArt-Run-Id. Ask returns nothing; Plan returns only the read-only tools (get_scene_info / get_world_state_snapshot / get_object_info / get_viewport_screenshot / describe_node_type / bpy_api_lookup / get_addon_status); execute_blender_code and export_scene count as write and are rejected + audited.
• The addon is a socket server: close Blender and the whole group fails (the error explicitly says "can't connect to addon", not a vague timeout). The app does not launch Blender and has no headless mode — get_viewport_screenshot even requires the window to be visible (minimized captures fail and fall back to the window grab). Connection state refreshes every 4 seconds in the Settings panel; get_addon_status checks versions on demand.