ENVOY / FORWARD VELOCITY

# talk to
your network.

Envoy is an MCP server embedded inside your `.toe` that gives your AI assistant direct access to the live session — operators, parameters, connections, pixel output. It doesn't describe what a network might look like. It builds the one you asked for. Say what you want. Watch it build.

Setup Envoy → See all 47 tools

THE DIFFERENCE

## blind vs. live.

Your AI assistant can suggest what to build — but without a connection to the live session, it can't see your network, read your parameters, or act on what's running. Envoy changes that in one toggle.

### without Envoy

- AI can describe networks — not build them
- AI works from assumptions, not live state
- Manual back-and-forth: AI suggests, you implement
- AI guesses at network state — no live feedback
- Visual feedback requires you to describe the output
- Parameter values, cook errors, hierarchy — all invisible

### with Envoy

- AI connects directly to your live session
- 47 tools expose every aspect of the running project
- Say what you want — operators appear, connect, tune
- AI reads the actual network, not a description of it
- `capture_top` returns real pixel output as an image
- Cook errors, parameter values, hierarchy — all accessible

CAPABILITIES

## 47 tools.

Every aspect of a TouchDesigner session — operators, parameters, connections, scripts, layout, performance, visual output — exposed as MCP tools the AI can call directly.

■

### operator management

Create, delete, copy, rename, query. `create_op` takes any TD type string. `find_children` searches by name, type, depth, tags, or text content.

■

### read_tdn

`read_tdn` returns an entire subtree — operators, parameters, connections, DAT content — in one compacted call. 20–90× fewer tokens than walking the same network via `get_op` + `query_network`, with a 5× floor verified in CI. Default omission, `type_defaults`, and `par_templates` do the compression. Use it for structural reads; fall back to `get_parameter`, `get_op_errors`, or `get_dat_content` when you need live runtime values.

■

### parameter control

`get_parameter` returns the full context — value, mode, expression, range, menu entries, default. `set_parameter` writes any mode in a single call.

■

### connections

Wire operators together, disconnect inputs, and inspect the full connection graph — including COMP parent/child connectors.

■

### DAT content

Read and write text DATs (scripts, configs) and table DATs (structured data). Edit extension code in place without leaving the session.

■

### positioning & layout

`get_network_layout` returns all operator positions in one call. New operators extend existing rows — no overlaps, no guessing.

■

### annotations

Create, read, and modify network boxes and comment annotations. The AI groups and labels operators the same way a human would.

■

### performance monitoring

`get_project_performance` returns FPS, frame time, GPU temp, and a hotspot ranking of the most expensive COMPs. Bottlenecks surface without you pointing at them.

■

### code execution

`execute_python` runs arbitrary Python in TD's main thread. The escape hatch for anything that needs looping, branching, or full TD access between steps.

■

### introspection

Inspect the live TD Python API — classes, methods, properties — and call operator methods by name. The AI looks up the API while using it.

■

### Embody integration

Tag operators, query externalization status, force-save to disk — the full Embody lifecycle as MCP tools. Build something, externalize it, without switching focus.

■

### bridge meta-tools

`get_td_status`, `launch_td`, `restart_td`, `switch_instance` — run on the local bridge, available even when TD is not running.

■

### batch operations

`batch_operations` combines any set of tool calls into one round-trip. Position 10 operators, connect them, set their parameters — one request, not 30.

VISUAL FEEDBACK

## see the pixels.

Every other tool in Envoy works with structure — operators, parameters, connections. `capture_top` works with what's actually rendering. It captures a TOP's output as an image and returns it directly in the response. The AI sees the pixels — not your description of them.

This is the feedback loop that was always missing. The AI builds a compositing chain, captures the output at each stage, examines what it produced, and iterates — without you narrating the screen.

- Any TOP — compositing chains, render TOPs, feedback loops, generative textures. If it outputs pixels, the AI can see it.
- Inline or file — small captures return directly in the response. Larger ones save to a temp file with the path returned.
- Iterative — capture after each change. The AI builds visual intuition across a session, not from a single snapshot.

Eyes. The AI doesn't just build your network. It sees what it built.

ARCHITECTURE

## how it works.

Every tool call follows the same safe path from your AI client into the live TD session and back.

1. 01

   ### you say what you want

   Your AI client sends a tool call. A local bridge script forwards it to Envoy's server on `localhost` — nothing leaves your machine.

2. 02

   ### envoy queues it safely

   The request is validated and queued for TD's main thread. Envoy never touches a TD object directly — it waits for the safe window.

3. 03

   ### TD executes it

   TouchDesigner picks up the operation on its own thread, with full access to every operator, parameter, and connection in your project.

4. 04

   ### the result comes back

   The response returns to your AI client with recent log entries attached — cook errors, warnings, status messages. Full context, every time.

Bridge meta-tools (`get_td_status`, `launch_td`) are cached locally — always available, even when TD is not running.

RELIABILITY

## runs in your project.

Envoy lives inside your `.toe`. It starts with your project, stops when you stop it, and never exposes your session to the network. Every design decision treats that trust as load-bearing.

### thread-safe execution

The MCP server never touches a TD object. All operator access runs on TD's main thread, enforced by architecture — not convention.

### crash recovery

If Envoy goes down, it restarts itself — exponential backoff, up to three attempts. Port changes trigger a clean restart automatically.

### local only

The server binds to `127.0.0.1`. It's not reachable from the network. Your session stays on your machine.

### no hangs

Every operation has a hard 30-second timeout. Long-running tasks fail cleanly rather than blocking TD or freezing the bridge.

### always in context

Every response piggybacks recent log entries — cook errors, warnings, extension messages. The AI never loses context between calls.

ZERO SETUP

## auto-configured.

When Envoy starts for the first time, it writes a complete AI client configuration to your git repo root — or project folder if there's no git. Every file your AI client needs is generated and kept in sync.

.mcp.json Registers the Envoy bridge with Claude Code, Cursor, and Windsurf
CLAUDE.md Project context — what Embody is, how the network is structured, what tools to use
.claude/rules/ Always-loaded conventions — TD Python, parameters, network layout, MCP safety
.claude/skills/ On-demand reference — full tool catalog, TD API, operator creation, externalization
.claude/commands/ Slash commands — `/run-tests`, `/status`, `/explore-network`
.gitignore / .gitattributes Binary handling for `.toe` / `.tox` and externalized file tracking

Regenerate at any time: `op.Embody.InitEnvoy()` for MCP + AI config, `op.Embody.InitGit()` for git config.

THE WORKFLOW

## part of the loop.

Envoy is the forward layer — it gives the AI access to build. It works with the other two layers to close the full loop.

### Embody

lateral velocity.

The AI builds something via Envoy, then externalizes it using Embody's MCP tools. The work is immediately tracked, version-controlled, and restorable on next open.

### TDN

the substrate.

Envoy reads the live network via `export_network` to see what's on screen. It modifies the JSON and imports it back — changes appear instantly, and the diff is human-readable.

### Git

the record.

Every build session ends in a commit. The agent reads `git diff` at session start, understands what changed, and continues where it left off — without you summarizing anything.

Forward velocity. You describe. The AI builds, externalizes, and reads the diff next session. The distance between idea and network is the time it takes to say a sentence.

DOCUMENTATION

## go deeper.

### setup

Enable Envoy, connect your AI client, and verify the session is live.

→

### tools reference

Every tool, every parameter, every return value. The complete catalog.

→

### architecture

The dual-thread model, bridge design, instance management, and recovery paths.

→

### Claude Code

Auto-generated config — rules, skills, slash commands, and how they work together.

→