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)
• "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.

6. Security & limitations

• The service listens on 127.0.0.1 only, with token auth; file access is confined to the project root; secrets are never exposed.
• Concurrency gate: generate_image / generate_speech / 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 refuses 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).