Vantage Code Mode MCP Server

The Vantage Code Mode MCP Server lets Claude, Codex, Gemini, and other LLM clients work with Vantage: inspect and modify scene state, open and save files, probe and modify properties of scene objects, and run VScript payloads through the Scratchpad.

The LLM client sees named tools such as vantage_status, vantage_scene_inventory, and vantage_eval, plus Code Mode's execute tool for multi-step work.

Walking along a request path, from Server config to request's end

That is the whole shape: MCP client, installed server, VScript-aware tools, pipe transport, Vantage-side execution, VScript/helpers, and a controlled response path back to the model.

Related MCP server: Maya MCP

Install and client setup

The modified Vantage installer owns the setup. Client machines do not need Python, pip, virtual environments, PyInstaller, or a source checkout.

You normally do not run the helper commands by hand. Install and uninstall are installer hooks. --stdio is launched by the MCP client when an LLM uses Vantage MCP.

A first stdio connection is deliberately strict: Vantage must already expose the native bridge, and the server must establish a ready VScript before FastMCP serves tools or callbacks. Successful MCP status calls therefore run after that readiness proof. Standalone --diagnose reads raw native status and may observe the pre-bootstrap scriptingEnabled or vscriptLoaded flags instead.

Knowledge up front, references on demand

Agents do not have to guess the Vantage surface from memory or spend the hot path rediscovering its basic rules. The MCP initialization instructions include the stable VScript execution model, scene collections, object lookup rules, write-proof protocol, value-shape rules, and canonical failure tokens.

vantage://reference/index
vantage://reference/vscript-surface/camera/fov
vantage://reference/return-values/Vector.v

Those MCP resources provide deterministic routing and exact SDK facts without creating another domain tool or duplicating VScript as a typed mutation API. Code Mode can use the same direct tools inside execute:

await call_tool(name, params)

Use direct tools for direct actions. Use Code Mode when the agent needs loops, polling, retries, filtering, hashes, or several Vantage calls before returning a small final value. Code Mode orchestrates VScript; it does not replace it.

Pipe and protocol

The pipe is the strong local transport under the MCP server.

The native bridge currently passes 1 MiB as the advisory input and output buffer size to CreateNamedPipeW. Windows owns the actual pipe-buffer allocation and backpressure behavior. That advisory setting is not the protocol frame size.

Vantage-side execution

Vantage owns the scene, renderer, and VScript runtime. Apart from ping, commands are posted back onto the Vantage app thread before they touch host state.

LavinaApp is used for app-level work: get_status reads async app state and scene/script flags, open_scene enqueues Vantage's normal scene-load task, save_scene_as calls the product .vantage save entry point, open_script uses Vantage's script loader, and request_quit follows the normal main-window close path.

VScript eval is narrower. After the bridge gets the interactive core from LavinaApp, it fetches the scene's VScriptManager and runs VScriptManager::executeAdHocSnippet(...) through Vantage's Scratchpad path. The Scratchpad boundary supplies the MCP-owned mcpSceneObj alias from the loaded script's engine-owned scene object, so reads do not replace a running behavior script. Loaded script files themselves define MyLogic; VScript calls its constructor with sceneObj. The MCP result includes structured fields for success/failure, stdout, stderr, result capture, errors, and whether the scene changed.

The helper tools are there to avoid waste. For example, vantage_scene_inventory can return counts plus sampled cameras, lights, and nodes in one call. That saves the agent from making a chain of ad-hoc VScript queries and from dumping a full production scene into chat just to answer a small question.

Tool and reference surface

Vantage reference material is exposed as MCP resources rooted at vantage://reference/index, including deterministic routing, VScript surface members, and return-value shapes. get_schema belongs only to Code Mode's compact discovery surface; there is no duplicate vantage_get_schema tool.

Mechanically provable failures return a small structural envelope with a stable failure token, evidence, next action, and—when useful—the targeted reference URI. The server does not keep a catalog of task recipes or model-specific mistakes; the LLM remains responsible for authoring the VScript.

vantage_quit follows Vantage's normal dirty-scene prompt. The no-prompt shutdown command is kept for development and is not exposed as an LLM-facing tool.

vantage_start cannot rescue the first connection when Vantage is absent: lifespan must succeed before any tool can be called. It remains useful after an established server session loses Vantage because the MCP process stays alive and can launch the installed one-up executable with Home skipped.

Large responses without context flooding

The bridge can move large local payloads, but the MCP layer should return compact answers. A 10,000-node scene may have enough names and metadata to be large on the wire; the useful answer may only need counts, hashes, samples, or a filtered subset.

That is the intended path:

Vantage data -> native response chunks -> Python reassembly -> helper summary -> compact LLM answer

The latest stress report (below) measured large payload bodies inside tools and returned byte counts, lengths, hashes, timings, and samples instead of raw bodies. The reported visible token cost for the full stress ledger was low: 407 estimated LLM input tokens and 1,039 estimated output tokens.

Stress evidence

The latest recorded live battery passed 29 / 29 checks against an open Vantage instance.

Repository notes