Automation: arc docs

The Automation Bridge

On startup, arc binds a local TCP server on 127.0.0.1:3987. Commands received over this bridge are dispatched directly through the same command engine powering the UI, ensuring that:

Every change is recorded on the non-destructive undo/redo history stack.
All registered Lua plugin hooks fire consistently.
The 3D WebGL viewport and project trees re-render in real time.

bridge.json and Auth

To secure local access, arc generates a unique authentication token upon launch and writes it to bridge.json in the user configuration directory:

Bridge Configuration
Setting	Details
File Location	Linux: ~/.local/share/com.arc.cad/bridge.json macOS: ~/Library/Application Support/com.arc.cad/bridge.json Windows: %APPDATA%\com.arc.cad\bridge.json
Payload	{"port":3987,"token":"..."}
Port Fallback	Starts at 3987 and increments if busy. Overridable via ARC_BRIDGE_PORT.
Authentication	Send {"auth":"<token>"} as the initial message on connection.

Protocol

After handshake, exchange newline-delimited JSON commands over the TCP socket:

// Client request (one JSON object per line)
{"id":"1","cmd":"get_state","params":{}}
{"id":"2","cmd":"create_entity","params":{"document_id":"doc-1","geometry":{"type":"box","width":60,"height":20,"depth":60}}}

// Server response
{"id":"1","ok":true,"result":{"active_document_id":"doc-1"}}
{"id":"2","ok":true,"result":{"id":"ent-1","name":"Box 1"}}

Command Groups

Bridge Command API
Category	Available Commands
State	get_state, get_settings, get_plugins
Settings	set_settings
Documents	new_document, open_document, save_document, close_document, set_active_document, get_scene
Entities	create_entity, update_geometry, delete_entities, duplicate_entities, explode_entities, set_transform, set_entity_props, set_selection, raycast
History	undo, redo
Layers	add_layer, delete_layer, rename_layer, set_layer_visible, set_layer_locked, set_layer_color, set_active_layer
Export	export_scene (STEP / OBJ / binary STL)

MCP Stdio Client

The bundled crates/arc-mcp tool provides a standard Model Context Protocol (MCP) server over stdio. This enables AI assistants (Antigravity CLI, Claude Desktop, Cursor, IDE agents, and autonomous CLI tools) to model, inspect, and manipulate 3D scenes in Arc with zero friction.

AI Agent Design Principles

Automatic Document Resolution: Agents never need to juggle document IDs. Omitting document_id automatically operates on the active document or seamlessly creates a new project.
Direct High-Level Primitives: Call arc_create_box, arc_create_cylinder, arc_create_sphere, or arc_create_extrude with positions, Euler angle rotations (in degrees), and human color names or hex codes in a single tool call.
Constructive Solid Geometry (CSG): Apply boolean unions, differences (cutouts/holes), and intersections with arc_boolean.
Atomic Multi-Operation Batches: The arc_batch tool lets agents define entire complex assemblies (e.g., 20 parts with cutouts and standoffs) in a single turn using $alias variable references between steps.
Context-Friendly Inspection: arc_inspect_scene returns a clean, compact summary of scene entities without dumping megabytes of vertex floats into the LLM context window.

Configuration

Antigravity CLI (~/.gemini/config/mcp_config.json):

{
  "mcpServers": {
    "arc": {
      "command": "/path/to/arc/target/release/arc-mcp"
    }
  }
}

Claude Desktop / Workspace (.mcp.json):

{
  "mcpServers": {
    "arc": {
      "command": "cargo",
      "args": ["run", "--quiet", "--release", "--bin", "arc-mcp"]
    }
  }
}

MCP Tool Reference

Available Agent Tools in arc-mcp
Tool	Description
arc_create_box	Create a 3D solid box with width, height, depth, and optional corner_radius, position, rotation, color.
arc_create_cylinder	Create a 3D solid cylinder with radius and height.
arc_create_sphere	Create a 3D solid UV sphere with radius.
arc_create_cone	Create a 3D solid cone with base radius and height.
arc_create_torus	Create a 3D solid torus with major radius and tube tube radius.
arc_create_plane	Create a rectangular 2D planar reference face in the XZ plane with width and depth.
arc_create_extrude	Extrude a closed 2D polygon ([[x, y], ...]) vertically by height into a 3D solid.
arc_create_revolve	Revolve a 2D profile ([[x, z], ...]) around the central Y axis (e.g. vases, shafts, pulleys, domes).
arc_create_sweep	Sweep a circular tube of given radius along a 3D path polyline ([[x, y, z], ...]).
arc_create_loft	Loft a solid skin through multiple cross-section polygons (sections).
arc_create_wall	Construct an architectural wall along a 2D polyline footprint (path, width, height).
arc_create_stair	Construct a parametric staircase with width, rise, run, and step count.
arc_create_sketch	Create 2D or 3D wireframe sketch curves (polyline, circle, rectangle, or line).
arc_boolean	Apply CSG operations (union, difference, intersection) between first_id and second_id.
arc_transform	Translate, rotate (Euler angles in degrees), or scale an existing entity by ID.
arc_set_color	Assign display color (#hex, red, steel, or RGBA array) to an entity.
arc_delete	Delete one or more entities by ID (entity_ids: [...]).
arc_inspect_scene	Return a token-efficient summary of the scene (IDs, names, types, positions, colors) without dumping raw mesh vertices.
arc_clear_scene	Wipe all entities from the active document for a clean slate.
arc_export	Export the CAD scene to stl, obj, or step.
arc_batch	Atomic batch execution: run multiple operations in one turn with $alias variable cross-referencing.

One-Turn Assembly with arc_batch

An AI agent can construct an entire multi-part assembly with holes in a single turn:

{
  "operations": [
    {
      "alias": "base",
      "tool": "create_box",
      "args": { "width": 100, "depth": 100, "height": 10, "color": "steel", "name": "base_plate" }
    },
    {
      "alias": "hole",
      "tool": "create_cylinder",
      "args": { "radius": 10, "height": 30, "position": [0, 5, 0], "name": "center_hole_tool" }
    },
    {
      "tool": "boolean",
      "args": { "operation": "difference", "first_id": "$base", "second_id": "$hole" },
      "alias": "plate_with_hole"
    },
    {
      "tool": "create_cylinder",
      "args": { "radius": 6, "height": 50, "position": [0, 30, 0], "color": "#3b82f6", "name": "shaft" }
    }
  ]
}

Raw Socket Example

Python script demonstrating direct programmatic modeling via localhost TCP:

import json, socket, pathlib

info = json.loads(pathlib.Path("~/.local/share/com.arc.cad/bridge.json").expanduser().read_text())
sock = socket.create_connection(("127.0.0.1", info["port"]))
f = sock.makefile("rw", encoding="utf-8", newline="\n")

# Authenticate
f.write(json.dumps({"auth": info["token"]}) + "\n")
f.flush()
assert json.loads(f.readline()).get("ok")

def send_cmd(req_id, cmd, **params):
    f.write(json.dumps({"id": str(req_id), "cmd": cmd, "params": params}) + "\n")
    f.flush()
    return json.loads(f.readline())

state = send_cmd(1, "get_state")["result"]
doc_id = state["active_document_id"]

# Place a parametric 3D box
res = send_cmd(2, "create_entity", document_id=doc_id,
               geometry={"type": "box", "width": 100, "height": 40, "depth": 60})
print("Created solid entity:", res)